Welcome. This is a technical version of Arvantti Harness®, intended for development teams. Let's see the real architecture of the arv-harness repository: the Core in TypeScript, the CLI as a stable frontier, the adapters, the terminals with node-pty and xterm, the Brain on SQLite + sqlite-vec and the desktop Shell in Electron. Arvantti Harness® is a registered trademark of Arvantti Labs, a brand of Sequoia Space.

Four specific pains. 1) Models do not save state between turns: the harness forwards system prompt, tool and MCP definitions, skills metadata, CLAUDE.md/AGENTS.md and all history; the accumulated cost of a session grows O(n²). 2) The caching prompt works by identical prefix byte by byte (order: tools → system → messages). Adding or removing tools, changing models or agents, or compacting breaks the prefix and everything after that is reprocessed. Adding content at the end doesn't break it. 3) Subagents and sessions that share context or checkout become contaminated. 4) Without a common control plan there is no record of who did what. Source: ADR-0002 and ADR-0003 (context/cache) and the non-canonical ARVANTI-full-summary.md exploratory design note.

This is how the harness harness works. On the left, the AI ​​code harnesses or CLIs that your team already uses: Claude Code, Antigravity, GPT Codex, OpenCode, Kimi, Pi, Gemini, Microsoft Copilot or local models. Each is connected via a slim adapter, which translates its actions and delegates to Arvantti's stable CLI; The adapter does not have business logic nor is it a source of truth for capabilities (ADR-0001). At the center is the Arvantti Harness® Core, common to all: policy (what is allowed), grants (permissions per session), tasks (traceable work), receipts (evidence in NDJSON), brain (context and memory) and route and secret keepers. The Core operates on your environment: repositories, real terminals (PTY, pseudo-terminals), connectors and files. Arvantti does not disable the subagents, tools or native flows of each harness (ADR-0003): it wraps them with the same control plane.

Top-down reading: a request enters through a host (Electron Desktop, the TUI, the Pi adapter with /arvantti or your own shell), crosses the stable CLI (bin/arvantti.mjs → src/cli: parseCliArgs, executeCli, formatCliResult) and reaches the Core (src/core: project-policy, guardians, grant-document, task-contract, task-receipt, work-intake, session-assignments, brain-repository, context-measurement...). The Core does not do I/O nor does it contain an LLM loop: the adapters (src/adapters: pi, terminal with node-pty and ANSI buffer, brain with sqlite-vec, obsidian-vault for SDD, local-store in .arvantti/, transcript, process) do the job effectively. There is one adapter for each AI code harness (Pi, Claude Code, Antigravity, GPT Codex, OpenCode, Kimi), always slim and delegating to the CLI. The execution layer is real PTYs (pseudo-terminals: real consoles created by program, with node-pty), authorized worktrees and foreground processes. Desktop, TUI, and CLI are not permission authorities; the policy is revalidated at the border of the effect. Cloudflare (ADR-0010, milestone H16) will be management, governance and knowledge sharing, never an execution host.

We prefer CLI over MCP: each MCP server adds tool definitions to the context prefix, inflates it, and breaks the cache on activation or removal; The CLI is invoked by bash, which all harnesses already have, and returns paginated, composed, and auditable output. ADR-0002: The CLI is the stable boundary for humans, agents, and adapters. Avoid registering a native tool for each integration (which would inflate the prefix and break the cache) and force responses that are paginated, composed, and suitable for entering the end of the context. The 11 commands that exist today are in src/cli/command.ts: help, version, catalog, pull, policy, task, flow, plan, sdd, shell and tui; --json changes the output format. Actual syntax: plan assess <summary> [--steps=N] [--reversible] [--external-effect] [--sensitive] [--architecture] [--uncertain] [--multi-actor] [--force=direct|task|sdd-lite|sdd-full]; sdd create --level=lite|full --id=ARV-SDD-#### <slug> <title>; sdd inspect <bundle>; task <create|claim|complete> <task-id> [title]; task link <task-id> <sdd-id> <sdd-path>; pull <profile|skill|flow|integration> <id> <revision> (requires ARVANTTI_SUBJECT_ID); policy <shared|local> <path>; flow code-review <review>. The example IDs (T-12, ARV-SDD-0042) are illustrative. Note: commands like "arvantti brain search" or "arvantti skill show" appear in ADR-0002 as future examples and do not exist yet. Risk assumed: bash is not sandbox; the CLI validates arguments, routes and scopes.

Notice: The frame for this slide comes from the ARVANTI-complete-summary.md exploratory note, which is NOT canonical; the canonical is ADR-0002, ADR-0003 and the agentic architecture subplan. 01 Stable prefix: ADR-0003 fixes the native tools/MCP profile at login; changing it live is explicit exception with documented cache impact. Per-session assignments are implemented; measuring cache with real Pi is still pending (H2/H3), that's why Partial. 02 Lazy pointers: three-level design catalog → flow → instructions per agent; keep the chain flat (2 tier is sturdy). Implemented: arvantti catalog and arvantti pull with assignments and receipts (ARV-US-0010). 03 Inject at end: pull by CLI implemented; context-push mode exists as an allocation type but the normal flow is pull by check-in, without injecting work into an active session. 04 bash + CLI: The Pi adapter delegates to the CLI (ARV-US-0008). Quote: context-budget.json declares maxItems, maxCharacters, optional maxTokens (ceil(UTF-8/4 bytes) heuristic, not actual tokenizer) and the paginate/summarize/reject overflow policy; local pull rejects overflow content instead of truncating it.

In addition, there is multi-agent coordination: each agent works on their terminal and they share tasks and receipts. And a Council Room, a space where agents contrast their proposals and reconcile a decision before acting, with the person as the final arbiter. Each agent in its own terminal/session, with its context and, if it writes code, its own worktree: this way they are not contaminated. The decision tree comes from the exploratory (non-canonical) note: evaluate in order and stop at the first decisive answer; correction priority (1–2) > capacity (3) > optimization (4). Author's testing data in that note: Pi boots with ~800–1,000 input tokens and Claude Code with ~20,000, so with light harnesses opening separate terminals is cheap. PTY (pseudo-terminal) means a real terminal created by program: the agent thinks he is at a normal console and Arvantti can see what comes and goes. local embedded PTY with node-pty, ANSI buffer with @xterm/headless, tabs, context menu and structural restoration in the TUI (ARV-SDD-0024); hierarchical groups and bindings persisted in .arvantti/terminal-workspace.json; when restoring, sessions appear as unknown and never relaunch themselves (ARV-US-0016). The terminal is free: it does not require policy or grants and is NOT a sandbox; Arvantti does not control a pi or claude that you throw there. Desktop Electron has real PTY, multiple tabs, recursive splits and reattach after reloading the renderer. Worktrees: the Core has a binding contract; creating the first worktree or branch requires explicit human authorization (ADR-0004). The Session Relationship Canvas (ARV-SDD-0025) is planned.

Advantages of this architecture: it is private and can live on the computer, in a local cloud or in the company's private cloud, without the data leaving that environment; It's a single file, with no database server to operate; stores text (FTS5) and vectors (sqlite-vec) in the same database, so hybrid search does not require synchronizing two systems; and backups are trivial with VACUUM INTO. Additionally, since the domain is port-based, it can be projected to the cloud without changing the agents. The business brain is memory in a graph: what is known, what was decided and what happened, always with origin and temporality. Logical model (architecture/brain-data-model.md): Project, Knowledge source and revision (provenance and digest), Document and chunk, Brain snapshot (separated from commit and dirty delta), Entity, Claim and Relation (with trust and validity), Evidence (safe locator + digest), Decision (what, who and with what evidence), Actor, Embedding profile and Vector reference. ADR-0005 (accepted): New SQLite + local sqlite-vec for Brain V1; PostgreSQL and Neo4j are discarded due to premature operating costs and the hybrid due to synchronization complexity. sqlite-vec serves only the vector index behind VectorIndexPort; the domain goes by BrainRepositoryPort and BrainQueryPort. node:sqlite is experimental on Node 22. Cloudflare D1/Vectorize would be a future Cloud projection, not the source of truth. ARV-US-0012 Status: partial. The tasks live in the Tasks capability (implemented) and the pending decisions as Brain entity are in the model, even without query CLI. Commands like "arvantti brain search" are future design, they don't exist yet.

Arvantti Harness® gives AI three brains. One, the project brain: the project memory, with its SDD, tasks, documents and context, so that each agent starts knowing where the work is. Two, the decision graph brain: a graph of who decided what, when and with what evidence, including pending decisions. Three, understanding repo: a code graph with the map of functions, modules and dependencies of the repository, so that the AI ​​understands the code in one pass. Instead of reading file by file, the agent consults the map: it spends fewer tokens, makes fewer mistakes, and proposes better changes. Everything lives in the local Brain, with provenance, and agents query it by ports and CLI.

Work Intake / SDD Resolver (src/core/work-intake.ts, ARV-US-0003) recommends one of four methods based on explicit and harness-neutral signals. Actual rules: SDD complete if there is architectural decision, 8 or more steps, or 3 or more signals between external effect, security sensitivity, material uncertainty and multiple actors; also recommendsAdr. SDD Lite if there is uncertainty, multiple actors, external or sensitive effect, or 4 or more steps. Direct only if it is exactly one step and --reversible. If not, Task. The recommendation never creates a Task or an SDD, does not grant permissions, and does not replace the policy; --force=direct|task|sdd-lite|sdd-full register your choice. Afterwards, the creation is explicit: arvantti sdd create --level=lite|full --id=ARV-SDD-#### <slug> <title> (ARV-US-0013 and 0014). The complete SDD is a primary note plus seven phases: brief, spec, design, tasks, execution, verify and closing. arvantti sdd inspect <bundle> detects ID and lifecycle drift without writing Markdown, and arvantti task link keeps Task as the authority. Everything is Markdown Obsidian-native: YAML frontmatter, wikilinks and normal folders. The Task ↔ SDD flow with receipts was verified end-to-end (ARV-SDD-0017).

Key user history: If an agent attempts to read, display, or change an API key (for example in an .env file), the path and operation pass through the watchdog; secrets require explicit human authorization (ADR-0004), and any secret-like value appearing in the output is replaced by [REDACTED] before reaching transcripts, receipts, or logs. Actual authorization string (src/core/guardians.ts and project-policy.ts). 01 authorizeProjectPath lexically normalizes the path: it must be relative to the project and not traversal; only then is policy evaluated, and the caller only opens the route after an allow. 02 Shared policy (.arvantti/policy.shared.json) plus restrictive local override (policy.local.json); A local override never removes restrictions. 03 Grants in .arvantti/grants.json: link subject, project, resource and operation, and are revoked; in V1 they do not expire on their own. The operations with effect (EffectOperation) are the six of the line in monospace. 04 redactOutput recursively sanitizes the output before transcript, receipts or logs: configured literals and secret-like assignments are replaced by [REDACTED]; It is an exit defense, it does not authorize reading a secret. Partial because the full persistent connection to Room/log is missing (ARV-US-0007). There is also a dependency guardian for pnpm. ADR-0004: continuous safe allows editing, stage and commit within an already authorized task and worktree; the first branch or worktree, merge, push, PR, deletes, secrets, network or external MCP, deploy and publish require explicit human authorization.

Arvantti Harness® works with agent loops. The development loop plans with SDD, implements, tests and reviews, and starts again until the task is closed. In parallel, the security loop runs: agents that monitor files and outputs, detect keys and sensitive data, block the reading of .env files and other secrets, and write the output and notify a person when something tries to exit. Thus, while some agents build, others take care that no key or sensitive data escapes. The loops are supported by the gatekeepers, policy and grants from the previous slide.

Receipts are append-only records, independent of the ALL of each harness. TaskReceipt (src/core/task-receipt.ts): schemaVersion, receiptId, taskId, projectId, actorId, action (created | claimed | completed | linked), status and recordedAt; They are persisted as NDJSON in the local-store. PullReceipt (pull-receipt.ts): receiptId, assignmentId, sessionId, target (id and revision), deliveredAt, outcome delivered | rejected and summary. Technical IDs are stable v7 UUIDs, independent of routes and titles. There is also a redacted transcript receipt and contextual observations; its full persistence is still ongoing (ARV-SDD-0007 running). In roadmap (ARV-US-0025): a lightweight, append-only, filterable audit CLI for changes not covered by Git (SDD, Design MD, Brain decisions, agentic configuration), with model declared, reported or unknown; failing a log warns without blocking, and a receipt that is not durable is never asserted. About ISO/IEC 42001: say it carefully. Traceability is intended to support AI management practices aligned with the standard; Arvantti is not certified nor does it certify anyone.

Although we prefer CLI, Arvantti also has a native MCP layer: clients and harnesses that work with MCP can connect directly, always behind the same policy, the same grants and the same registry. The table comes from the exploratory (non-canonical) note, Zoho scenario: if you activate a native MCP mid-session, its tools enter the prefix and the history is reprocessed on activation and again on deactivation. If Arvantti connects the MCP, sends the list of commands as a message and the agent bash them via the CLI: the cache is left intact; When you deactivate it, Arvantti stops accepting those commands and warns you. Bonus: credentials live on Arvantti and every call is logged. The canonical (master plan §11 and agentic subplan): MCP is integration/adapter, not orchestration core; the decision is CLI-first local and MCP is limited to future external providers, behind adapter, policy and consent; external network/MCP is always human gate. Milestones: H10 (Code Intelligence, LSP and limited local MCP) and A8 of the agentic subplan (optional packages/MCP/external services with ADR, threat model, consent, cost and rollback per integration).

The adapters connect each code harness with AI (Pi, Claude Code, Antigravity, GPT Codex, OpenCode and Kimi) and delegate to the local Arvantti CLI. Decision history: ADR-0006 proposed a local-first Web Shell as the primary interface and the TUI as the secondary one; ADR-0007 and ADR-0009 accompanied her. The three were replaced by ADR-0011: Electron Desktop is the first graphical Shell and the Web is left for Cloudflare, without a terminal. Desktop (apps/desktop, Electron 45 + xterm 6, development preview, ARV-SDD-0037/0038): PTY and privileged effects live in the main process; The preload is minimal and the IPC is authorized by sender, frame and origin. There is verified CSP, flow control with ACK and watermarks (270 KB and 1 MB bursts in E2E tests), shutdown with added confirmation, reattach after reloading the renderer and a 5 minute soak. After relaunching the app, metadata and layout are restored, never processes. There is no installer, signature or updater. TUI: arvantti tui and arvantti shell; Streaming, permissions, resize and end-to-end cancellation are pending. Shared logic is not duplicated per platform. ADR-0008: Every functional shell must have a real PTY; Mocks are only valid for design or isolated tests.

ADR-0001: each harness enters as a thin adapter (Pi, Claude Code, Antigravity, GPT Codex, OpenCode, Kimi), never as a Core or as a source of truth for capabilities or policy. ADRs live in the documentation vault (Arvantti-Harness/adr). 0004: continuous safe within already authorized task, worktree and branch; First worktree or branch creation, merge, push and destructive actions require authorization. 0005: SQLite + sqlite-vec for Brain V1, with D1/Vectorize as future Cloud projection. 0008: A graphical shell without actual PTY is not deliverable. 0010: Cloudflare is management, governance and shared knowledge, never a host of terminals, PTYs or commands. 0011: Electron Desktop first; A local Web Shell is not built with Connector now. 0012: no forks per operating system, only small adapters with a common contract.

Closing for technical teams: we invite you to a demo of the CLI, the TUI and the Desktop preview, or to propose an adapter for the harness used by your team. Contact: Andrés Quiceno, CTO of Engineering, [email protected]. Web: arvantti.tech. LinkedIn: Arvantti Labs and Sequoia Space Latam. Arvantti Harness® is a registered trademark of Arvantti Labs, a brand of Sequoia Space.