Documentation

A complete guide to installing, configuring, operating, and extending aricode in real codebases. This page is intentionally detailed: it is meant to be the reference manual for the CLI, REPL, knowledge graph, dreaming system, and safety model.

Overview

aricode combines four things that most CLI coding agents keep separate: an interactive REPL, a persistent project memory, a codebase knowledge graph, and an autonomous exploration mode called dreaming. The result is a local-first agent that does not need to rediscover your project from scratch every time you open it.

The core operating model is simple:

• You provide a task, question, or planning request.
• The model receives tools for reading files, editing code, running approved commands, querying the world model, and spawning bounded subagents.
• aricode records what the model learns into persistent artifacts, updates the knowledge graph live, and uses that state to improve later work.

Requirements

For the smoothest experience, use a terminal with standard ANSI support and a model that is genuinely capable of code editing, tool use, and longer reasoning loops.

Installation

The easiest path is the install script, which checks your environment, installs dependencies, builds the TypeScript sources, installs the CLI globally, and verifies the command surface.

curl -fsSL https://install.aricode.dev | sh

You can also install manually through npm:

npm install -g aricode

For local development from a checkout:

npm install
npm run build
npm link

Verify the install:

aricode --version
aricode --help

First Launch

Run aricode inside a project directory:

cd your-project
aricode

On the first launch in a workspace, aricode initializes session state and attempts to load a persisted knowledge graph for that project. If none exists, it offers to build one. The REPL then becomes your persistent operating surface for that workspace.

/init
/dream
/plan refactor the auth middleware to support JWT
fix the null pointer in src/parser.js

Operating Modes

aricode can be used in three primary ways:

The interactive REPL is the most capable mode. It is where planning, dreaming, transcript history, patch review, and session continuity all come together.

Configuration

aricode keeps a mix of global and per-project state. Global provider information lives outside the project, while project artifacts live under .aricode/. Existing legacy state is migrated automatically on first run.

~/.aricode/providers.json

Provider definitions, base URLs, active provider state, and related backend configuration.

~/.aricode/{workspaceHash}/

Persistent session state keyed by workspace path. Stores transcript history, summaries, and session configuration.

.aricode/

Project-local artifacts such as the knowledge graph, dream outputs, plans, memory, and hooks.

You can change the active model, backend, profile, context size, and context includes from inside the REPL at any time.

/model qwen2.5-coder:32b
/backend http://localhost:11434/api
/profile compact
/ctxsize 128000
/include src
/include test
/files

Providers & Models

aricode is backend-agnostic as long as the endpoint behaves like the OpenAI chat completions API and the selected model can reliably handle coding tasks and tool calling. In practice that means local Ollama, llama.cpp-based stacks, vLLM deployments, LM Studio, and other compatible systems all fit.

Ollama

ollama pull qwen2.5-coder:32b
aricode --base-url http://localhost:11434/api --model qwen2.5-coder:32b

You can also configure this interactively:

/backend http://localhost:11434/api
/model qwen2.5-coder:32b

Other OpenAI-compatible endpoints

/backend https://your-endpoint.example/v1
/model your-model-name
/provider list
/provider add

Project Layout

After initialization and use, you should expect aricode to maintain the following project-local structure:

.aricode/
  ARICODE.md
  graph/
  dream/
  plans/
  hooks.json

And the following global structure per workspace:

~/.aricode/
  providers.json
  {workspaceHash}/
    session.json
    transcript.jsonl
    summary.md

The exact contents grow over time as the agent works, dreams, plans, and accumulates project memory.

REPL Workflow

The REPL supports both direct natural-language tasks and slash commands. A typical work session looks like this:

1. Open the project and let aricode load or build the graph.
2. Run /init if you want a fresh project memory file.
3. Ask for direct work, or use /plan to separate planning from execution.
4. Review pending patches with /diff and apply with /apply.
5. Use /history, /status, /graph, and /dream as persistent support tools.

/status
/graph stats
/plan add structured logging to the worker queue
/execute
/diff
/apply

Command Reference

The REPL exposes a fairly broad slash-command surface. The list below reflects the currently shipped command registry.

Session & UI

Models, Providers & Context

Task Execution

Codebase & System Inspection

Memory, Setup & Dreaming

Knowledge Graph

The knowledge graph is aricode’s persistent structural memory of the codebase. It is not just a file index. It tracks symbols, imports, ownership relationships, runtime-adjacent structure, provenance, and higher-value relationships such as mirrors or connected modules.

The graph supports status views, codebase queries, context generation, and dream targeting. It is one of the main reasons aricode gets better on later sessions instead of remaining stateless.

/graph
/graph stats
/graph query auth middleware
/graph explain parser tokenizer

Project Memory

aricode maintains a persistent project memory file at .aricode/ARICODE.md. Older memory files are migrated automatically. It is intended to capture durable architectural context, conventions, terminology, and known constraints that should inform every later turn.

The memory file is generated by /init and enriched from several sources:

• Knowledge graph summaries and high-value symbols.
• Dream findings and architectural observations.
• Convention extraction from the codebase.
• Manual human edits.

If you want aricode to internalize a non-obvious project rule, ARICODE.md is the canonical place to put it.

Autonomous Dreaming

Dreaming is aricode’s autonomous exploration mode. Instead of waiting for a task, aricode walks the codebase with a phased strategy and produces durable artifacts for later use. Dreaming is useful when a codebase is large, under-documented, or evolving quickly.

Dream phases

• Survey identifies important files, high-centrality symbols, and structural hotspots.
• Triage clusters likely areas of interest or risk.
• Deep Dive investigates concrete questions in targeted areas.
• Futures maps likely future directions, risks, and refactor opportunities.
• Synthesis writes the results back out as durable artifacts.

/dream
/dream --depth shallow
/dream summary
/dream browse
/dream explore

Artifacts are written under .aricode/dream/ and can later feed planning, memory generation, and graph-guided retrieval.

Planning & Execution

aricode separates planning from execution when you want it to. Planning mode is ideal for larger refactors, multi-step migrations, and work that should be reviewed before code is touched.

/plan migrate the worker queue to structured events
/execute

Typical flow:

1. Run /plan <task>.
2. Review the generated plan and any clarifying questions.
3. Approve or revise the plan.
4. Run /execute when ready.
5. Inspect pending changes with /diff and apply with /apply.

For smaller tasks, you can skip planning and ask directly in natural language or via /run.

Subagents

For broader or parallelizable work, aricode can spawn subagents. These are bounded agents with inherited context and constrained capabilities. They are useful for large codebase exploration or breaking down a complex problem without flooding the main context with raw intermediate work.

Subagents inherit the main session’s safety model and are subject to concurrency and budget limits so they remain support workers, not uncontrolled autonomous branches.

Tool Surface

The model-facing tool surface is what turns aricode from a chat shell into a coding agent. The exact implementation evolves, but the current core toolset centers on file access, editing, shell execution, graph queries, scratchpad state, planning, and lifecycle control.

Command Safety

aricode uses a default-deny command policy. The model cannot simply run arbitrary shell code. Commands are classified into tiers, validated, and either allowed, blocked, or escalated into an approval flow.

Environment variables are sanitized before agent-executed commands. Sensitive keys and tokens are stripped from the command environment unless you deliberately opt into a broader mode.

/privileged on
/privileged off

Behavioral Compilation

When aricode reads structured test failures or runtime evidence, it can extract behavioral witnesses and compile them into a repair-focused behavior patch. This helps the agent distinguish between incidental code changes and actual contract-level corrections.

BEHAVIOR PATCH
Iteration 2: 8 -> 3 witnesses

REPAIR: normalizePhone (src/phone.js:5)
  equality: "(415) 555-0100" -> "+14155550100"

This system is especially useful when several failing tests reduce to one root-cause function or contract mismatch.

Edit Intelligence

aricode does not treat file mutation as the end of the story. After edits, it can run a secondary layer of analysis that checks whether the change is plausible in the context of the project.

• Linting for supported languages.
• Convention checks against existing naming and structure patterns.
• Blast-radius awareness through graph dependencies and mirrors.
• Regression cues from previously observed behavioral evidence.
• Optional hooks for formatting or custom automation.

Hooks System

Hooks let you attach your own automation to aricode lifecycle events. They are configured in .aricode/hooks.json and can be used to run formatters, local checks, setup scripts, or custom telemetry.

{
  "hooks": {
    "post-edit": ["npm run lint --fix ${file}"],
    "post-write": ["prettier --write ${file}"],
    "pre-command": ["echo 'Running: ${command}'"],
    "post-command": ["echo 'Finished: ${command}'"],
    "session-start": ["echo 'Session started'"],
    "session-end": ["echo 'Session ended'"]
  }
}

Hook output is incorporated back into the working session so the model can react to it.

Sessions & Artifacts

aricode persists both workspace-global and project-local artifacts so that it can resume context across restarts.

Because sessions persist, commands like /history, /new, and /reset matter operationally. They do not just affect the visible transcript, they affect how much prior state aricode carries forward.

Languages & Environment

aricode supports a mixed-language world model and parser stack. The current documented language surface includes JavaScript, TypeScript, Python, Go, Rust, Java, Kotlin, Swift, C, and C++.

Common environment variables include:

ARIADNE_MODEL
ARIADNE_BASE_URL
ARIADNE_API_KEY
ARIADNE_PRIVILEGED=1
ARIADNE_CONTEXT_TOKENS

The command policy also recognizes many development toolchains, including npm, yarn, pnpm, bun, cargo, go, python, node, git, make, and related tools.

Troubleshooting

Model seems weak or unreliable

Use a stronger coding-capable model first. Many issues attributed to aricode are actually backend model failures in tool selection, long-horizon reasoning, or code synthesis quality.

Knowledge graph is stale or missing

Run /graph stats to inspect current graph state. If the project was never initialized, allow the initial graph build. If you need a fresh start, rebuild or reset the workspace state.

Agent keeps asking for approvals

That usually means the requested task crosses from read-only activity into mutating or privileged command tiers. Use /privileged on only when you intentionally want the agent to access a broader command surface.

Dream artifacts are missing

Run /dream directly and inspect .aricode/dream/. If your session never entered dreaming or was interrupted early, the artifacts may simply not exist yet.

Session context feels confused

Use /new to start a fresh conversation in the same workspace, or /reset to clear broader workspace state if you need a clean baseline.