I Built KIRA: A Local-First AI Agent That Has to Prove Its Work

Disclosure: I am the maker of KIRA Superapp and Orchestrator V1. This is a technical build story, not an independent review.

Most AI assistants are good at producing an answer. The harder question is whether they actually did the work they claim to have done.

I built KIRA Superapp around that gap. KIRA is an open-source, local-first agent runtime for Apple-silicon Macs. Its orchestration model can run on the machine, working memory stays local, voice can stay local, and actions pass through permission gates. When KIRA uses a tool, the tool result - not the model's confidence - determines whether the task is complete.

Its decision layer is Orchestrator V1, a model built to plan tool use instead of merely producing conversational answers.

KIRA should not say a task is complete unless the runtime has evidence from the tool that performed it.

TL;DR

• Local model: Orchestrator V1 runs through MLX on Apple silicon.
• Local working state: chats, memory, logs, artifacts, and downloaded models stay on the Mac by default.
• Local voice: Whisper handles speech-to-text and Kokoro ONNX supports text-to-speech.
• Permission gates: mutating tools ask before changing files, running commands, or calling external services.
• Result verification: KIRA continues from real tool output instead of declaring success from generated text.
• Honest networking: web research and configured connectors go online only when those features are used.

The code and installation instructions are on GitHub. I want technically specific feedback, including failed installs and broken agent loops - not manufactured praise.

More than a chatbot

A chatbot receives a prompt and returns text. An agent has a harder job: decide whether it has enough information, choose the right tool, execute it, interpret the result, and decide whether another step is required.

KIRA's loop is:

User goal
  -> Orchestrator V1 chooses the next step
  -> KIRA executes the selected tool
  -> the real result returns to the runtime
  -> the model evaluates that evidence
  -> repeat until the task is genuinely complete

The model is the planner. The runtime owns execution, permissions, and proof. A language model can write a convincing sentence saying a file was created or a command succeeded. KIRA should report that outcome only after the relevant tool confirms it.

What local-first means in KIRA

Local-first is not a privacy slogan. It shapes how the application runs and stores data.

Local orchestration

KIRA uses MLX, optimized for Apple silicon. The installer downloads Orchestrator V1 into a local model directory. KIRA can also discover compatible model folders in common local locations, including LM Studio directories. It rejects cloud-only iCloud placeholders instead of pretending an incomplete model is ready.

Orchestrator V1 is also available in GGUF format for compatible local runtimes.

Local voice

An Apple-optimized Whisper model provides local speech-to-text. A Kokoro ONNX path provides local text-to-speech, so spoken input and output do not have to be sent to a cloud voice service.

Local memory with boundaries

KIRA stores bounded recent continuity and selected durable preferences locally. The memory layer filters likely secrets such as passwords, API keys, private keys, credentials, and tokens. Retrieved memory is context, not a fresh command that should automatically run.

Provider settings, usage records, chat history, memories, logs, generated artifacts, and downloaded models are excluded from Git. Optional provider credentials are stored in the macOS Keychain instead of source control.

Local-first does not mean offline theater

Some features are inherently networked. Web research must contact websites. MCP connectors can communicate with external services. Optional model providers send the data required for the operation the user requested.

Capability	Default location
Orchestrator V1 inference	Local Mac via MLX
Whisper speech-to-text	Local Mac
Kokoro text-to-speech	Local Mac
Chat history and memory	Local files
Generated artifacts and logs	Local files
Optional API credentials	macOS Keychain
Web research	Network, when requested
External providers and connectors	Network, when configured and used

The goal is not to claim that every feature is offline. It is to keep the core intelligence and personal working state local while making external access explicit and task-dependent.

Permission gates are part of the product

Local software can still cause damage if it receives broad access without boundaries. A local agent may edit files, execute commands, interact with an IDE, call connectors, or create automations.

KIRA keeps mutating file, command, IDE, MCP, and automation actions behind explicit permission gates. The aim is not to make the model appear fearless. It is to make the system predictable enough to trust.

Private reasoning is filtered before display and before chat persistence. Users should see progress, permission requests, useful evidence, and the final outcome - not an uncontrolled reasoning dump.

One runtime instead of disconnected demos

The point of calling it a Superapp is not that one interface magically does everything. It is that the following capabilities share one orchestration, evidence, and permission layer instead of behaving like unrelated demos.

What makes KIRA a Superapp

KIRA is intended to be one local place where a user can think, research, create, code, inspect the Mac, work with files, use voice, schedule follow-up work, and connect external services when needed. The user does not have to translate every goal into a sequence of applications and commands first.

The same conversation can become a web investigation, a verified document, a slide deck, a coding task, a system report, an IDE workflow, or a scheduled task. The important part is not the number of buttons. It is that every path shares the same context, local memory boundaries, permission model, execution ledger, and completion rule.

KIRA also keeps the model and the runtime in different roles. Orchestrator V1 interprets the objective and chooses the next capability. The runtime owns execution, secrets, sandboxing, permissions, and verification. Specialists handle focused work such as research, media, documents, slides, and artifact inspection. That separation lets the system combine many capabilities without pretending the language model itself performed every action.

Diagonal orchestration: thinking across the whole workspace

I describe KIRA's approach as diagonal orchestration. This is a design metaphor, not the name of a separate model or a claim that private chain-of-thought is exposed.

A conventional assistant often moves vertically through one fixed pipeline: prompt, model, answer. A basic tool router moves horizontally across a flat list of functions. KIRA can move diagonally: from the user's high-level goal into the particular system context, evidence source, specialist, application, and verifier needed at that moment—then back to the shared task ledger before choosing the next branch.

Think of Orchestrator V1 as a conductor. The conductor does not play every instrument. It decides which section enters, when another section must wait, and when the performance has actually reached its ending. In KIRA, tools and specialists are the sections; returned evidence is the score everyone follows; permission gates decide whether a consequential action may begin.

For example, “research a topic and build a presentation” can move diagonally through web research, source collection, media gathering, the slides specialist, and the artifact verifier. “Find what is slowing down my Mac” can move through system and memory reports, a read-only optimisation scan, and—only if the user approves—a separate mutation step. The route is shaped by evidence rather than a predetermined demo script.

The pattern has four rules:

1. Start from the goal, not a favorite tool. The orchestrator selects the capability that fits the current evidence.
2. Cross domains without dropping context. Research, files, coding, media, and applications remain branches of one task.
3. Return to evidence before moving on. A branch must report a result, failure, or artifact path to the shared ledger.
4. Let the runtime—not model confidence—decide what is allowed and what counts as complete.

Diagonal orchestration is how KIRA aims to feel like one coherent workspace rather than a folder of unrelated AI demos.

Every KIRA tool in one place

This is the current registered tool surface in the public repository. The uppercase names are KIRA's execution primitives. Users can normally describe a goal in natural language and let Orchestrator V1 choose the right tool.

Planning, evidence, and specialist agents

• BRANCH_REGISTRY and TREE_STATUS expose the execution tree, returned evidence, errors, and completion state.
• SANDBOX_PROFILE reports the sandbox policy used by a branch.
• SPECIALIST_REGISTRY and SPECIALIST_TASK list and run fixed research, media, slides, document, and artifact-verification specialists.
• MODEL_SCAN, SUBAGENT_REGISTRY, SUBAGENT_CREATE, and SUBAGENT_TASK find compatible local models and assign focused work to local subagents.

Research and media specialists may work in parallel. Slides and document specialists consume returned evidence, then the artifact verifier checks the resulting PPTX, DOCX, or PDF before KIRA treats it as complete.

Computer and system inspection

• OS_MAP maps KIRA's local workspaces and readable locations.
• SYSTEM_REPORT reports macOS, processor, memory, storage, and related facts.
• APP_LIST and WINDOW_REPORT inspect installed applications and current window context.
• SCREENSHOT_CONTEXT captures visible UI evidence when a task needs it.
• NETWORK_REPORT and MEMORY_REPORT inspect network state and memory-heavy processes.
• VIRUS_SCAN performs a read-only heuristic scan and can use ClamAV when installed; it does not silently delete or quarantine files.
• OPTIMISE_SCAN finds large, old, duplicate, temporary, or review-worthy files and apps without changing them.

Files and local investigation

• READ_FILE and LIST_DIR read files and list directories inside an allowed scope.
• SEARCH_FILES searches file contents; FIND_IN_COMPUTER runs a scoped read-only investigation.
• HASH_FILE calculates a SHA-256 hash; FILE_COMPARE compares two files; ARCHIVE_PREVIEW inspects an archive before use.
• ZIP_CREATE creates a ZIP artifact.
• WRITE_FILE, APPEND_FILE, MOVE_PATH, and DELETE_PATH create, extend, move, or delete content. Because these change local state, they require permission.

Web research and media

• WEB_SEARCH runs a focused search; WEB_RESEARCH fetches multiple result pages and returns readable source evidence.
• WEB_OPEN, WEB_FETCH, and WEB_BROWSE open or retrieve an exact page when required.
• WEB_IMAGE_SEARCH finds visual candidates; WEB_IMAGE_DOWNLOAD saves a selected image with source information.

These tools use the network only when invoked. Returned pages and assets are evidence, not trusted instructions.

Documents, presentations, and drafts

• NATIVE_DOCX, NATIVE_PPTX, and NATIVE_PDF build Word documents, slide decks, and PDFs in the local artifact workspace.
• PDF_TO_PPTX converts PDF pages into an image-based presentation.
• NOTE_DRAFT, CALENDAR_DRAFT, and REMINDER_DRAFT prepare notes, calendar details, and reminders for review instead of silently publishing them.

Applications, coding, IDEs, and connectors

• OPEN and CLOSE control an exact application, file, folder, or URL.
• IDE_OPEN and IDE_CONTEXT open a project in a supported editor and read relevant context.
• IDE_PASTE_RUN places code or a command into an IDE execution surface after permission.
• PROJECT_INDEX builds a bounded project index; PROJECT_COMMAND runs a project-scoped command behind a permission gate.
• MCP_DISCOVER, MCP_BOOTSTRAP, MCP_DRAFT, MCP_SETUP, and MCP_APPLY discover, prepare, and apply connector configuration in controlled stages.
• APP_INTEGRATION reads or prepares supported app context; BLENDER_CONTEXT inspects Blender integration context for 3D workflows.

KIRA also contains optional coding harness paths for Codex and DeepSeek, with provenance and upstream licenses documented in the repository.

Clipboard, commands, and automation

• CLIPBOARD_READ and CLIPBOARD_WRITE read or update the macOS clipboard.
• SCHEDULE_TASK creates a resumable scheduled task after review and permission.
• SHELL, COMMAND, and TERMINAL execute command-line work inside the applicable sandbox and permission boundary.
• PYTHON and APPLESCRIPT run only through the controlled mutation path.

Local voice

Whisper provides local speech-to-text, while the Kokoro ONNX path provides local text-to-speech. Voice requests enter the same Orchestrator V1 loop as typed requests, so speaking to KIRA does not bypass its evidence or permission rules.

One permission rule across the whole catalog

Safe observation can run without interruption when it stays inside KIRA's allowed readable map. Reading outside that map requires approval. Actions that write, delete, move, execute, configure connectors, control an IDE, change the clipboard, or schedule future work are routed through explicit permission gates. Network tools are used only for tasks that actually require external information or a configured service.

Hardware and installation

The current release targets Apple-silicon Macs (M1 or newer) and does not support Intel Macs. It requires Python 3.11 or 3.12, at least 16 GB of unified memory, and about 12 GB of free disk space. Twenty-four GB of memory is recommended.

Internet access is required for the initial dependency and model downloads. After installation, local features run from assets stored on the Mac; network-dependent features still require a connection.

git clone https://github.com/saggamer/KIRA-Superapp.git
cd KIRA-Superapp
chmod +x INSTALL_MACOS.command DOWNLOAD_MODELS.command superapp
./INSTALL_MACOS.command
./superapp

KIRA is released under the Apache License 2.0. Review the Orchestrator V1 model card, its base-model terms, and licenses of optional integrations before use.

The buyer's questions - and the builder's answers

Why install this instead of using a hosted assistant?

Install KIRA if local inference, local working data, inspectable code, and permission-aware tools matter to you. If you want a zero-setup hosted experience, an early local project may not be the right choice yet.

Is everything completely offline?

No. Core model, memory, voice, and artifact workflows can operate locally. Web research and configured external connectors use the network because that is their purpose.

Is it production-ready?

It is an early open-source project. It needs clean-install testing, stronger documentation, adversarial agent-loop tests, and real-world feedback.

Try it - and try to break it

• KIRA Superapp: https://github.com/saggamer/KIRA-Superapp
• Orchestrator V1 for MLX: https://huggingface.co/saggamer/Orchestrator_V1
• Orchestrator V1 GGUF: https://huggingface.co/saggamer/Orchestrator_V1_GGUF

If you have a supported Mac, try one real workflow and report what happens. A useful issue includes your hardware, macOS version, model format, exact prompt, expected result, and the tool result you actually saw.

I would especially value criticism of the permission model, memory boundaries, and tool-result loop. Those are the parts that determine whether an agent is merely persuasive or genuinely dependable.

What I need tested

KIRA is early software, so the most valuable feedback is reproducible evidence. If you try it, please test one complete workflow rather than only opening the chat screen.

Useful test cases include:

• installing on a clean supported Mac;
• checking whether local model discovery finds the correct folder;
• starting local speech recognition and text-to-speech;
• asking KIRA to create a real file and checking the returned path;
• denying a permission request and confirming the action stops;
• forcing a tool failure and checking that KIRA does not claim success;
• using web research and checking that networked behavior is clear;
• reviewing what is stored in local history and memory.

A strong issue report includes the Mac model, unified-memory size, macOS version, Python version, model format, exact prompt, expected result, observed tool result, and relevant logs with secrets removed.

Why publish this now

The local-agent ecosystem needs more than model benchmarks. It needs repeatable tests for permissions, memory boundaries, tool execution, failure recovery, and completion claims. Those runtime details determine whether an agent is trustworthy in daily work.

I am publishing KIRA now because external testing will expose assumptions that are invisible on the development machine. If the installer is brittle, say so. If a permission prompt is confusing, show the exact workflow. If the agent claims success after a failed tool call, that is a high-priority bug.

The goal is not to win a demo. The goal is to build an agent whose behavior can be inspected, challenged, and improved in public.

Join the build

You can star the repository if the direction is useful, but testing is more valuable. Open an issue with a reproducible failure, suggest a safer permission boundary, or propose a benchmark for the tool-result loop.

Repository: https://github.com/saggamer/KIRA-Superapp

Thanks for reading - and if you test KIRA, please be demanding.