Ada CLI is HOILAB's fork of pi.dev (earendil-works/pi): the pi binary becomes ada-cli, config moves to ~/.ada/, and the fork auto-syncs with upstream daily so security fixes and new models land immediately. See ADA-CLI.md for the full sync mechanics. New issues and PRs from new contributors are auto-closed by default — see CONTRIBUTING.md.

Ada CLI is a coding agent built on pi.dev's proven minimal terminal core, with an Ada Intelligence Engine layered on top: autonomous goal pursuit with a mandatory evidence-backed judge, sandboxed parallel workflows, a traceability graph that gates "done" on observed evidence, durable cross-session memory with a tamper-evident audit log and PII scanning, encrypted secrets, and a native desktop app — all wired to the same settings.json your terminal already uses.

Where most coding agents ask you to trust a single long-running chat, Ada is built to be auditable: every autonomous action either has cited evidence behind it or it doesn't happen.

• Everything is optional and inspectable. The core stays as minimal as pi.dev's — four tools (read, write, edit, bash) by default. Autonomy, memory, and orchestration are opt-in layers you can turn off in settings.json.
• Autonomy requires a signed-off contract. The Goal Engine won't touch a codebase until you /goal approve its plan, runs fixed TDD phases, and never marks work done without a judge citing evidence for it.
• Nothing is "done" on the model's word alone. The Work Graph gates completion on observed evidence — a passing test, a real diff, a verified command — not a claim in the transcript.
• Memory is compliance-ready by default. The Memory Engine blocks PII before it's ever written to disk and keeps a hash-chained audit log of every write and rejection.
• Secrets stay off disk, and out of reach of the agent. The built-in Vault is a local encrypted store shared across the CLI, desktop app, and subagents of an unlocked session. Provider credentials and MCP tokens never enter the model's context. An explicit @vault:NAME reference does expand into the prompt — that is its purpose, so the model can use the secret in a command — but the expansion is redacted in everything persisted and displayed. The agent cannot read the vault: core/aprobacion/politica.ts denies it permanently, and that denial survives yolo.
• Teams get a GUI, not just a terminal. The Ada Desktop app (Tauri + Next.js) reads the exact same SDK and config as the CLI — no parallel product to maintain.
• Extensible instead of opinionated. No baked-in MCP, sub-agent framework, or permission popups — build exactly the workflow you need with extensions, skills, or third-party Ada packages. See Philosophy.

Getting Started

npm install -g --ignore-scripts @hoilab/ada-cli

export ANTHROPIC_API_KEY=sk-ant-...
ada-cli

Or authenticate with an existing subscription: run ada-cli, then /login. First run in a new project asks you to trust the folder — see Project Trust.

Compliance controls in detail — ledger, retention purge, machine policy, art. 9 detection, OTLP and SBOM — with what each one proves and what it does not: Compliance.

Full walkthrough: Quickstart · Providers & models · Windows · Termux · tmux

One limitation of the published package

ada-cli session <id> <op> (compact, rename, fork, kill, ops) needs a protocol extension point that this fork adds to @earendil-works/pi-{client,protocol,server}. Those are upstream packages: the published @hoilab/ada-cli resolves them from the npm registry, so an installed copy does not carry it. The command says so instead of failing with an opaque error. Everything else — including serve, attach and the whole agent — works from the published package.

A source build has no such limitation.

Building from source

Organisations that will not install from a public registry can build the same artifact locally. dist/ is what the published package and the desktop app consume, so it has to be built — running from src/ is not the same thing.

git clone https://github.com/HOILAB/ada-cli.git
cd ada-cli
npm ci                                   # exact versions from npm-shrinkwrap.json
npm run build --prefix packages/coding-agent
npm link --prefix packages/coding-agent  # puts `ada-cli` on PATH

To verify the build before trusting it:

npm run check          # types, lint, pinned deps, shrinkwrap, startup budget, fork budget
npx vitest run         # the full suite (from packages/coding-agent)
ada-cli --version

ada-cli update only runs when you ask for it and it queries the npm registry for this package, so a source build stays put until you rebuild it. Nothing phones home — see Telemetry and update checks.

Measured against the alternatives

Four coding tasks, the installed package (not the source tree), the same free OpenRouter model as the competing agent, comparing each one's own session logs:

| task | Ada | oh-my-pi | |---|---:|---:| | queue: fix a bug and add a method | 4 calls | 4 | | parser: honour quotes in CSV splitting | 4 | 10 | | retry: two bugs at once | 5 | 4 | | stack: add a method, throw on empty | 4 | 4 | | total round trips | 17 | 22 |

Both produced correct code on all four — verified by running the result, not reading it. Ada uses somewhat more context per turn (its system prompt carries the compliance doctrine, and it re-reads a file after editing to verify), and fewer round trips, which is what costs time and money per call.

Re-run on the release candidate (0.85.0) with a different free model (x-preview-f-free via the same gateway for both agents) and freshly written task fixtures, same method — installed package, executed results, each one's own session logs:

| task | Ada | oh-my-pi | |---|---:|---:| | queue: fix a bug and add a method | 8 calls | 8 | | parser: honour quotes in CSV splitting | 13 | 15 | | retry: two bugs at once | 7 | 4 | | stack: add a method, throw on empty | 7 | 10 | | total round trips | 35 | 37 |

Again 8/8 correct across both agents. On this model the aggregate favours Ada, with per-task wins split both ways — the honest reading is functional parity with fewer round trips, not dominance.

The one feature where the competing agent still led — reading PDFs, which it does by rendering the document in a headless browser and screenshotting it — is closed as of this release: read now extracts a PDF's text layer with node:zlib alone. It reports the three states that matter (text extracted / scanned, no text layer / unreadable) instead of letting a scanned document pass for an empty file; what it deliberately does not do is reproduce exact layout, which would need the browser back.

Built for Enterprise

• Governed autonomy. Permission modes (plan / manual / auto / yolo) and the Goal Engine's askBefore brakes gate irreversible actions (publish, delete, spend) behind explicit approval, in both the CLI and the desktop app. manual asks before every write; auto is the default; plan makes the tree read-only.
• Evidence over assertions. The Goal Engine's judge and the Work Graph's gates both require cited, observed evidence before anything counts as complete — no autonomous run can silently mark itself done.
• Retention you can defend. ada-cli audit purge --dias N --politica "..." deletes old ledger files by writing a chained tombstone first — which period, how many entries, under what policy, and the closing hash. audit verify then reports the gap as explained rather than as tampering, so complying with GDPR art. 5.1.e stops looking like covering your tracks. --dry-run shows exactly what would go, down the same code path that removes it.
• A policy the user cannot switch off. A third configuration scope lives where the operating system requires administrator rights to write (/Library/Application Support/Ada/, /etc/ada/, %ProgramData%\Ada\). It can only ever restrict: a modoMaximo ceiling lowers the requested permission mode and never raises it, and tools listed in denegadas stay denied even in yolo. There is deliberately no environment variable pointing at another file — that would be the back door that voids the policy with one export. ada-cli politica shows whether it is in force, and whether the file is one this account could edit. Every decision records which rule decided it.
• Privacy and audit built in. memoryPrivacyLevel: "strict" (default) blocks PII before it's persisted; every memory write, rejection, and search is hash-chained in an audit log via /memory-audit — designed to support GDPR/AI Act obligations without extra tooling.
• Secrets isolation. Provider credentials and MCP tokens never enter the model's prompt context, and nothing in the vault touches disk unencrypted. auth.json is encrypted at rest with AES-256-GCM under a key held in the system keychain.
• Budgeted, bounded runs. Every autonomous surface (Goal Engine, Workflows) enforces turn limits, repeat-loop detection, a stop-file kill switch, and token/cost budgets — no open-ended spend.
• Deployable as CLI or desktop. Same SDK, same settings.json, same audit trail whether your team works in a terminal or a GUI.
• Stays current automatically. A deterministic daily sync (scripts/sync-ada.sh + GitHub Action) re-bases onto upstream pi.dev, so security fixes and new provider support land without manual patch-tracking.

Ada Intelligence Engine

pi.dev is deliberately minimal — its own philosophy is to skip sub-agents and plan mode and let each team extend it their own way. Ada CLI takes the opposite bet: it ships that orchestration layer as part of the product.

| Module | What it's for | |---|---| | 🎯 Goal Engine (/goal) | Pursues an objective autonomously, turn by turn, through fixed TDD phases, gated by a contract (doneCriteria + verifyCommand) you must approve before it starts. A mandatory judge requires cited evidence before anything is marked done, backed by safety brakes (turn limits, loop detection, stop-file, cost/token budget). | | ⚙️ Workflows (/workflow) | Orchestrates multiple agents in parallel via sandboxed JS scripts, budgeted and resumable after an interruption. Ships 5 ready-to-use builtins: deep research, code review, product build, codebase audit, multi-perspective. | | 🕸️ Work Graph (/graph) | A typed graph connecting intent → requirement → task → file → test. Gates block declaring work "done" without observed evidence — never on the model's word alone. | | 🧠 Memory Engine (/memory-audit, /memory-consolidate, /memory-insights) | Durable 3-layer memory (global, project, past failures) with full-text session search, a tamper-evident audit log, and a PII scanner that blocks sensitive data before it's ever stored. | | ✨ Prompt Optimizer | Before processing a request, decides whether to ask up to 3 clarifying questions (clarify) or rewrite it as a structured prompt (enhance). | | 🔐 Vault (/vault) | Passphrase-encrypted local secret store, shared across the CLI, the desktop app, and subagents of an unlocked session. | | 🖥️ Desktop app | Tauri 2 + Next.js, running on the exact same SDK and settings.json as the CLI. pi.dev is terminal-only. | | ⏰ Scheduler (ada-cli schedule) | Recurring work that runs inside ada-cli serve. maxRuns and expiresAt are mandatory — an open-ended recurring job is open-ended spend, and nobody remembers to turn it off. Each job gets its own session so two schedules never contaminate each other's context. | | 🔁 Continual Harness (ada-cli refine) | Turns what a finished session learned into durable notes injected into future prompts. Every proposal requires cited evidence (file:line, a command and its output, a message from you); the ones without it are rejected and shown to you. The base system prompt is never touched. | | 🌐 Web tools (web_search, web_fetch) | Native TypeScript, key from the encrypted vault, SSRF-guarded — private ranges and the cloud metadata endpoint are blocked before the request is made. Opt-in per subagent: network access is never inherited from readOnly. | | 🔌 MCP (mcp_list_tools, mcp_call_tool) | A real TypeScript MCP client with tokens from the vault. Exactly two tools, never one per remote tool: a 40-tool server would flood the system prompt and displace the cacheable prefix. | | 💾 Prompt cache optimizer | Reorders the system prompt so stable content comes first, meters the real hit rate per provider, and repairs provider-specific quirks. With prefix caching the cost of a change depends on its position, not its size — on DeepSeek a miss costs 31x a hit. | | 🖧 Resident sessions (ada-cli serve / attach / session) | Work survives closing the terminal. Reattach to watch or steer, and run compact, rename, fork or kill over the socket. | | 🧩 Editor integration (ada-cli acp) | Speaks Agent Client Protocol over stdio, so Zed and any ACP client can drive Ada instead of the TUI. |

| | pi.dev (upstream) | Ada CLI (this fork) | |---|---|---| | Product | CLI (pi) | CLI (ada-cli) + desktop app | | Multi-turn autonomy | Not included — skips sub-agents and plan mode by design | Goal Engine: contract-first loop, fixed TDD phases, mandatory judge with cited evidence, safety brakes | | Orchestrated parallelism | No | Workflows: sandboxed JS scripts (node:vm) with agent()/parallel()/pipeline(), resumable journal, 5 builtins | | Work traceability | No | Work Graph: typed graph with evidence-gated completion | | Cross-session memory | Only within the active session / context files (AGENTS.md) | Memory Engine: 3 durable layers + full-text session search + tamper-evident audit log + PII scanner | | Prompt optimization | No | Prompt Optimizer: clarify or enhance before processing | | Secrets | No | Vault, encrypted, shared CLI/desktop/subagents | | Slash commands | pi.dev's base set | + /goal /workflow /graph /vault /memory-audit /memory-consolidate /memory-insights | | Anti-recursion | N/A | goal_*/workflow/graph_add_nodes/memory tools register only on the main session — subagents never self-orchestrate | | Upstream sync | — (it is upstream) | Deterministic daily reset + delta reapply, no manual merges |

PrimeIntellect-ai/prime-agent is also built on earendil-works/pi, with a persistent-Python-kernel execution model and a self-improving "Continual Harness". Full breakdown with sources: docs/AUDIT.md §8.

| Capability | Ada CLI | Prime Agent | Edge | |---|---|---|---| | Background sessions surviving terminal close | ada serve / ada attach / ada session | Daemon-backed attach/detach | Even | | Editor integration (Agent Client Protocol) | ada acp | acp mode | Even | | Scheduling / recurring work | ada-cli schedule, with mandatory maxRuns/expiresAt | /heartbeat, cron schedules | Even | | Self-improving instructions | ada-cli refine, every proposal requires cited evidence | /refine with rollback snapshots | Even | | Agent-to-agent messaging | Deliberately blocked (anti-recursion by design) | Built in | Design trade-off, not a gap | | Executable / Python-backed skills | Markdown only, by choice | Python packages + skill-creator | Prime Agent | | MCP integration | Native TypeScript client, tokens from the vault | Protocol lives inside the Python kernel | Ada CLI | | Web search | web_search/web_fetch, key in the vault, SSRF-guarded | Python skill, key in plaintext auth.json | Ada CLI | | Prompt-cache optimisation | Prefix stabilisation + per-provider hit-rate metering | None | Ada CLI | | Work traceability graph | Yes, evidence-gated | None | Ada CLI | | Native desktop app | Yes | TUI-only | Ada CLI | | Dedicated encrypted secrets vault | Yes | Plain auth.json | Ada CLI | | Mandatory evidence-backed judge | Yes, by default | User-configurable gates, not forced | Ada CLI |

See docs/AUDIT.md for the full technical audit, the exact fork/sync mechanics, and the capability-by-capability parity breakdown — including what we deliberately chose not to copy, and why.

The three guarantees, and what they are not

These are enforced in code, not by policy. Each line is checkable — open the file and read it.

| Guarantee | Where it is enforced | |---|---| | A goal cannot complete without a judge citing evidence. The judge is independent, sees only the goal, its doneCriteria, the verifyCommand and the cited evidence, and runs on its own session — on a different model when the workers are configured on a cheaper tier. No verdict, no completion. | workflows/goal-engine/engine.ts (runJudge), resource-loader.ts | | Subagents cannot orchestrate or write durable memory — structurally. The tools are not registered in a subagent's registry at all; it is not a permission check that could be bypassed or relaxed. Asserted in test/anti-recursion-tools.test.ts. | agent-session.ts (_isSubagentSession gates) | | Memory is written through a PII scanner and a hash-chained audit log. Rejections are logged too, and /memory-audit verifies the chain. | memory-engine/scanner.ts, memory-engine/audit.ts |

What Ada does not claim. The workflow interpreter rejects scripts that use require, process or import, but that check is a text filter, not a security boundary: node:vm is escapable through the constructor chain, and we verified it — a script reaching the host process, its 67 environment variables and its working directory. Node documents this itself: «The node:vm module is not a security mechanism.» The filter's real job is to turn naive host access into a readable error, and the guard for that limit lives in test/workflows-sandbox-limite.test.ts. The leaf agents Ada spawns are ordinary sessions with read/bash/edit/write and the same OS permissions as any coding agent, yours included. Ada is not an OS sandbox; for untrusted work, run it in a container. What Ada does contain is narrower and real: credentials live in an encrypted vault that is permanently out of the agent's reach, every tool call and command is recorded in a hash-chained ledger, and extensions go through the same approval policy as the agent.

Engine command reference, settings.json schema, and model-routing rules: docs/AUDIT.md §4 covers the architecture; slash-command syntax for /goal, /workflow, /graph, /memory-*, and /vault is documented inline via --help and /hotkeys in the CLI itself.

Documentation

• Quickstart — install, authenticate, run a first session
• Using Ada — interactive mode, slash commands, CLI reference
• TUI reference — full keyboard shortcuts, message queue, tree navigation
• Sessions · Compaction — branching, forking, context management
• Settings — global and project configuration
• Security · Containerization — project trust, sandboxing
• Extensions · Skills · Prompt templates · Themes · Ada packages
• SDK · RPC mode · JSON mode — headless and embedded usage
• docs/AUDIT.md — fork architecture, sync mechanics, and the full competitive analysis

Philosophy

Ada stays extensible instead of opinionated: no baked-in MCP (build a skill or extension instead — why), no forced sub-agent framework, no permission popups, no built-in to-dos. Build exactly what your workflow needs with extensions, skills, or a third-party Ada package — see the original pi.dev rationale.

Contributing & Development

See CONTRIBUTING.md and docs/development.md.

License

MIT

See Also

• @earendil-works/pi-ai — core LLM toolkit
• @earendil-works/pi-agent-core — agent framework
• @earendil-works/pi-tui — terminal UI components