YouBothAgent▾

You — Business rules and flows you own. Read these yourself.

Both — Know the idea; your agent follows the details.

Agent — Conventions and references your agent follows. Look up as needed.

CLI Reference▾

Commands Workspace Application Library Module Scalar Package Page Primitive Workflow Quality Pipeline Context Agent Guideline

AkanJS Reference▾

akanjs/base akanjs/common akanjs/constant akanjs/fetch akanjs/signal akanjs/server akanjs/client akanjs/webkit

UI Reference▾

Overview Core Display Forms Overlays System Agent Customization

Code CLI

akan code runs an AI coding agent in your terminal that already knows this workspace. Ask it to add a field and run the validation loop, with no editor, no MCP client setup, and no explaining the module conventions first.

Put a model key in the workspace .env, e.g. DEEPSEEK_API_KEY for the default model.
Run akan code to start a session, or akan code "<prompt>" for one run.

What The Agent Brings

Coding Tools

read · write · edit · ls · grep · find · bash

Reads, edits and runs commands in the workspace, and fetches and searches the web. The profile decides which are on.

Akan Tools

plan_workflow · apply_workflow · run_validation

Context inspection, workflows, repair and validation: the same set akan mcp gives an editor's agent.

Akan Skills

akan-module · akan-store · akan-validate · …

Playbooks for the scaffolding chain, the store surface and the validation loop, read when a task needs one. Add your own in ~/.akan/code/skills or .akan/code/skills.

Project Rules

AGENTS.md

The workspace's AGENTS.md sits in the context window, so the agent follows the conventions from the first turn.

Not akan mcp, Not akan agent install

Command	Agent runs in
↳ What it is
akan code	Your terminal
An agent of its own that already carries the tools and rules above.
akan mcp	Your editor
A server that lets an editor's agent reach this workspace's tools.
akan agent install	Your editor
Writes the rule files an editor's agent reads.

Three Ways To Run

One command runs in three modes, and the arguments pick one — there is no subcommand. They are checked in this order:

Mode	When
↳ What you get
RPC	`--rpc`
Serves akan wire frames over stdio for another process to drive.
Full-screen session	`--interactive`, or no prompt and no `--json` on a terminal
A chat you keep talking to. A prompt you pass becomes its first message.
One run	Any other call with a prompt
Runs the prompt to the end and prints each event. With `--json`, one JSON line per event.

Without a terminal, or with --json, a missing prompt is an error. In a pipe or a CI step, always pass one: akan code "add a comment module".
One run is the shape for scripts. It exits when the prompt is done, and --json makes its output machine-readable.

code

Runs the Akan coding agent. Pass a prompt for one run, or leave it off to open the full-screen session.

Signature

Arguments

promptString

What the agent should do. Left off on a terminal, the full-screen session opens.

Options

--appStringnullable · flag: -a

Narrows the agent to one app, rooted at apps/<app>. Without it, the whole repo is in scope.

--profileStringdefault locallocal | pod | review | web · flag: -p

Picks what the agent may do: its tools, approvals and session storage. See Profiles below.

--modelStringnullable · flag: -m

<provider>/<id>. Default: deepseek/deepseek-flash; without its key, the first available.

--jsonBooleandefault falseflag: -j

Prints one event per line as JSON. The full-screen session then opens only with --interactive.

--thinkingBooleandefault falseflag: -t

Prints the model's reasoning alongside its output.

--rpcBooleandefault falseflag: -r

Serves the agent over stdio as akan wire frames for another process. Wins over every other mode.

--resumeStringnullable · flag: -R

Reopens a stored session by id in the full-screen session. Only local and web save sessions.

--interactiveBooleandefault falseflag: -i

Opens the full-screen session even when a prompt is given, and sends that prompt first.

Notes

NameDescription

API key

Set <PROVIDER>_API_KEY in the workspace .env or your shell, e.g. DEEPSEEK_API_KEY.

resume id

When a full-screen session with a conversation closes, it prints akan code --resume <id>.

session files

Stored under .akan/code/sessions in the workspace. An id that is not there is an error.

denied paths

Every profile refuses .env, .env.*, secrets/, *.pem and *.key, whatever its allowlist.

Examples

Profiles

A profile bundles what the agent may do into one value, picked with --profile. It decides which tools exist, whether writes wait for approval, where sessions are kept, and how much of the project sits in the window.

Profile

Write & run

Web

MCP

Asks first

Saved

Waits for your answer (await)

local

✓

The default. Everything is on, and nothing asks for approval.

review

A reviewer: only read, ls, grep and find, no AGENTS.md, sessions in memory.

Ends the turn and picks it up later (suspend)

pod

✓

An isolated container with nobody watching it: everything but MCP is on.

web

✓

The reach of local, but every file write waits for your approval.

✓OnOff

await or suspend. await holds the turn open until you answer. suspend ends the turn and reopens one with your answer, so it survives a process restart.
Every profile carries the Akan tools and skills. review gets only the Akan tools that change nothing.
web asks before write and edit only. bash never waits for approval.
MCP servers come from two files. ~/.akan/code/mcp.json is yours and .akan/code/mcp.json is the checkout's; on a shared name the workspace entry wins.
--app is a real boundary. It moves the profile's root to apps/<app>, and file tools refuse any path outside it. That holds better than a prompt politely asking the agent to stay there.

The deny list is not a sandbox for bash. A command that names .env is refused, but a shell can still reach any path. The real boundary is the container the pod profile runs in.

Architecture · Agentic→

The agent that runs inside a rendered page instead of a terminal.

Agent CLI→

akan agent install, which writes the rule files an editor's agent reads.

akan mcp→

The MCP server that hands this workspace's tools to an editor's agent.

NextCommands