--- source_hash: ec46b0dce61f1f3810a8f5229f69c1d1284512ea449abae0460008d560b44134 post: using-it folder: ari-os shape: doctrinal --- # Using ARI-OS day to day — Context Pack (for agents) Agent-facing context pack for the published post `using-it`. Needles below are copied **verbatim** from the `.mdx` body (this page's literals live in the body itself, not in a composing component). Reproduce them exactly — do not paraphrase, re-case, re-hyphenate, or "fix" underscores vs hyphens. When the post and this pack disagree, the post wins: re-fetch `content/posts/ari-os/using-it.mdx` and re-extract. The load-bearing convention throughout: the **product is `ARI-OS`** (hyphen, caps), the **Python module is `ari_os`** (underscore). Every CLI below uses the underscored module path. Do not normalize either direction. --- ## 1. One-line gist ARI-OS's daily surface reference: the **slash commands**, **skills**, **Cortex memory MCP tools**, **dispatch**, the **monitor**, and the **control panel** — the exact verbs, tool signatures, flags, and subcommands you drive every day from one chair while workers run in the background. --- ## 2. NEEDLES (verbatim — do not confabulate) ### Frontmatter (exact) - `slug: using-it` - `title: "Using ARI-OS day to day"` - `folder: ari-os` - `type: how-to` - `status: published` - `date: 2026-06-15` - `summary: "The commands, skills, Cortex MCP tools, and the dispatch and monitor surface you drive every day."` - `related: [overview, install, brain]` ### Slash commands (10 — run inside the main session; name is the exact token) - `/brainstorm` — "Open a structured brainstorm that pulls intent and requirements out before any code is written." - `/dispatch` — "Hand a brief to a background worker and keep working in your own session." - `/dream` — "Run a memory consolidation pass, distilling raw capture into durable signal." - `/handoff` — "Write a clean handoff document so the next session can pick up where you left off." - `/monitor` — "Open the live monitor to watch every running worker in one place." - `/morning` — "Run the morning briefing: a maintenance check and a dashboard of what is in flight." - `/night` — "Close the day out with an end-of-day review layered on top of a consolidation pass." - `/prefetch` — "Warm the Cortex ahead of a task so the right context is loaded before you ask." - `/recall` — "Pull the most relevant past context for a query straight into the conversation." - `/remember` — "Save a fact, a decision, or a piece of thinking to the memory layer." ### Skills (10 — orchestrator can step into these by name) - `advisor` — "Advisor-driven development: the orchestrator plans, cheaper models execute, and complexity escalates back up." - `brainstorm` — "Explore intent, requirements, and design before any building begins." - `dream` — "Consolidate memory: orient, gather, distil, and prune." - `handoff` — "Produce a structured handoff so context survives the end of a session." - `morning` — "Assemble the morning briefing from maintenance state and active work." - `night` — "Run the end-of-day strategy review and consolidation." - `prefetch` — "Load the context a task will need before the task starts." - `recall` — "Retrieve relevant memory across the brain for a query." - `remember` — "Commit text to the shared memory layer." - `teach` — "Capture your methodology, patterns, and operating principles into memory drafts as you work." ### Cortex MCP server - MCP server name: `ari-os-cortex` (hyphenated — the server, not the module) - Manual registration (exact, note `python` not `python3`): `claude mcp add ari-os-cortex -- python -m ari_os.tools.cortex.mcp_server stdio` - Module path: `ari_os.tools.cortex.mcp_server` (underscored) — wired up by the install guide. ### Cortex MCP tool signatures (10 — exact, including defaults in parens) - `brain.recall(query, mode='default', k=12, token_budget=4000, session_id)` — "Recall the most relevant past context for a query." - `brain.remember(text, layer='semantic', source)` — "Store a memory. It dedupes by the sha256 of the text." - `brain.lineage(chunk_id)` — "Trace where a memory came from." - `brain.regions()` — "List the memory regions." - `brain.tracts(n=100)` — "List the strongest connections." - `brain.entities(kind, k=50)` — "List known entities." - `brain.relations(entity, k=50)` — "List an entity's relations." - `brain.modes()` — "List the retrieval modes." - `brain.see(image_path, mode='visual')` — "Describe an image. Off until LENS plus a local vision model are enabled." - `brain.lens(slug)` — "Apply an aesthetic lens. Off until LENS is enabled." - Default-off tools: `brain.see` and `brain.lens`. `brain.see` needs **LENS plus a local vision model**; `brain.lens` needs **LENS**. ### Dispatch — start a worker (exact command) - `python3 -m ari_os.tools.dispatch start --executor sonnet --task-file BRIEF.md --cwd ./worktree --label mytask` - Executors (only three, lowercase): `haiku`, `sonnet`, `opus` — "Pick the smallest one that can do the job, and escalate only when the work demands it." - Access-shaping flags: `--add-dir` (grant an extra directory), `--read-only` (no write access). - Hard rule: "Dispatch refuses a git repository root as `--cwd`. Point it at a worktree or a subdirectory instead, so a worker can never act on the whole repository at once." ### Dispatch — manage running workers (exact) - `python3 -m ari_os.tools.dispatch list` — shows what is in flight. - `python3 -m ari_os.tools.dispatch questions` — surfaces anything a worker is blocked on. - `python3 -m ari_os.tools.dispatch answer --answer "..."` — sends your reply to a specific worker. ### Monitor - Launch: `python3 -m ari_os.tools.monitor` - URL: `http://localhost:7777` — "Leave it running while you work, and you can see progress, questions, and completions without switching context." ### Control panel — base command + subcommands - Base: `python3 -m ari_os.tools.arios` - Subcommands: - `keys` — manages the API keys for any models you use. - `theme ` — switches the visual theme. - `toggle on|off` — turns a feature on or off. - `update` — pulls the latest version. - `cortex [value]` — configures the memory brain; `setting` is one of: - `status` - `embeddings ` - `mode ` - `wander on|off` - `ears on|off` - `lens on|off` - Worked examples (exact): - `python3 -m ari_os.tools.arios cortex status` — check the state of the brain. - `python3 -m ari_os.tools.arios cortex mode focus` — switch the retrieval mode to focus. ### Diagram + pullquote - Diagram `src`: `/posts/ari-os/dispatch-lifecycle.png` - Diagram `alt`: `The dispatch lifecycle` - Diagram `caption`: `A brief is dispatched to a worker, the worker runs in its own worktree, and it reports back to your session.` - Pullquote (load-bearing thesis sentence): `You direct from the chair. The workers run in the shadows.` ### Cross-references inside the body (exact hrefs) - Overview: `/documents/ari-os/overview` - Install guide: `/documents/ari-os/install` - Brain page (cited twice): `/documents/ari-os/brain` --- ## 3. GIST (the argument condensed) This page is the **operator's manual** for the daily surface, and it is built on one repeated shape: **you stay in the conversation and set direction; workers run elsewhere and report back.** Every section is an instance of that split. Three layers of verbs are enumerated. **Slash commands** (`/dispatch`, `/recall`, `/dream`, …) are what you type in the main session. **Skills** (`advisor`, `brainstorm`, `teach`, …) are the named capabilities the orchestrator can step into — a command usually invokes the matching skill, but the orchestrator can also reach for a skill unprompted. **Cortex MCP tools** (`brain.recall`, `brain.remember`, …) are what the model calls directly once the `ari-os-cortex` MCP server is registered. Dispatch is the delegation spine: one prompt becomes several background workers, each in **its own worktree**, gated by three executors (`haiku` / `sonnet` / `opus` — smallest that can do the job, escalate only when demanded) and two access flags (`--add-dir`, `--read-only`). The hard safety rule is that dispatch **refuses a git repository root as `--cwd`** — you must point it at a worktree or subdirectory, so no worker can act on the whole repo at once. Once running, the loop is `dispatch list` → `dispatch questions` → `dispatch answer`, with the monitor (`localhost:7777`) as the one live window onto all of it. The control panel (`python3 -m ari_os.tools.arios`) is the single configuration surface — keys, theme, feature toggles, updates, and the `cortex` subcommand whose settings (`embeddings`, `mode`, `wander`, `ears`, `lens`) are exactly the switches that change what the memory brain pulls and how. Two tools (`brain.see`, `brain.lens`) are default-off pending LENS (and, for `brain.see`, a local vision model), so an agent that assumes vision is available is wrong by default. --- ## 4. KEY LEARNINGS 1. **The daily surface is one shape, repeated.** Direct from the chair, workers run in the shadows. If you find yourself executing grind-work inline in the main session instead of dispatching it, you are not using the surface as designed — route it through `/dispatch`. 2. **Commands, skills, and MCP tools are three distinct layers.** Commands are what you type; skills are what the orchestrator steps into; tools are what the model calls. They often share a name (`brainstorm`, `recall`, `remember`) but are not interchangeable — do not conflate `/recall` the command with `brain.recall` the tool. 3. **Pick the smallest executor, escalate only on demand.** `haiku`, `sonnet`, `opus` — in that cost order. Reaching for `opus` by default defeats the point of the layer. 4. **Never dispatch against a repo root.** `--cwd` must be a worktree or subdirectory; dispatch hard-refuses a git repository root so a worker can never act on the whole repository at once. This is a safety invariant, not a preference. 5. **Two Cortex tools are off by default.** `brain.see` and `brain.lens` are gated behind LENS (and `brain.see` additionally needs a local vision model). Do not assume image/lens capability exists until those are enabled. 6. **The control panel is the single config surface.** Keys, theme, feature toggles, updates, and every cortex knob (`embeddings`, `mode`, `wander`, `ears`, `lens`) live under `python3 -m ari_os.tools.arios` — there is no second place to configure ARI-OS. 7. **`brain.remember` dedupes by sha256 of the text.** Re-storing identical text is a no-op; to update a memory, change the text. This shapes how you should phrase `remember` calls. --- ## 5. FILE INDEX (load-bearing — re-fetch to verify needles) Unlike the sibling `tools-and-plugins/ari-os` page, **this page's needles live in the `.mdx` body itself** (it is prose + JSX block components, not a single composing component). The literals to re-verify are: - `content/posts/ari-os/using-it.mdx` — the post under pack. **Primary source for every needle above**: the `SurfaceList` items (commands, skills, tools), the `` blocks (MCP registration, dispatch start, dispatch management, monitor, control panel + examples), the control-panel subcommand/cortex-setting bullet list, the `` props, and the ``. - `components/blocks` — the `Code`, `SurfaceList`, `WorkerFanOutFidget`, `Diagram`, `Pullquote` components imported by the post (referenced as `@/components/blocks`). They render props verbatim; they do not author the strings. - `components/ari-os/content.ts` — the shared `ARI_OS` object. This page does **not** render from it, but it confirms the module-path convention (`ari_os`, underscore) and the install/uninstall commands the install guide wires up. Cross-check the underscore/hyphen split here if a module path needle looks "wrong". - Sibling posts in the same folder (cross-linked, not needle sources for this pack): `overview.mdx`, `install.mdx`, `brain.mdx`, `advanced.mdx` — the install page wires the `ari-os-cortex` MCP server; the brain page covers modes, embeddings, regions, and consolidation in depth. External / asset refs to re-fetch if stale: - `/posts/ari-os/dispatch-lifecycle.png` — diagram asset (verify it exists in the public posts tree at the path shown). - `http://localhost:7777` — the monitor's bound port (verify it has not moved). > Backfilled 2026-07-18 from the published body; not needle-extracted at thought-time.