Akan.js
Docs
DocsConventionsReferencesCheatsheet
Akan.js
DocsConventionsReferencesCheatsheet
Akan.js

Released under the MIT License

    • Official Akan.js Consulting onAkansoftCopyright © 2026 Akan.js All rights reserved.System managed bybassman
    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▾
    CommandsWorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityContextAgentGuideline
    AkanJS Reference▾
    akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
    UI Reference▾
    OverviewCoreDisplayFormsOverlaysSystemAgentCustomization
    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▾
    CommandsWorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityContextAgentGuideline
    AkanJS Reference▾
    akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
    UI Reference▾
    OverviewCoreDisplayFormsOverlaysSystemAgentCustomization
    NextCommands

    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.
    1. Put a model key in the workspace .env, e.g. DEEPSEEK_API_KEY for the default model.
    2. 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
    CommandAgent runs in
    ↳ What it is
    akan codeYour terminal
    An agent of its own that already carries the tools and rules above.
    akan mcpYour editor
    A server that lets an editor's agent reach this workspace's tools.
    akan agent installYour 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:
    ModeWhen
    ↳ 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 runAny 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.
    Related Pages
    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.

    On this page

    Code CLI
    code
    Profiles