Introduction

Akmon is a terminal-native AI coding agent designed for developers who need control, portability, and accountability. It is intentionally built as a small Rust binary with a typed permission model, explicit provider selection, and an auditable execution trail.

This page explains why it exists, the design choices behind it, who it is for, and where it is intentionally not trying to compete.

The problem Akmon was built to solve

AI coding tools are now capable of shipping real features, but most teams still have the same fear: what exactly did it do, and why did it do that? In many products, you get polished UX and fast output, but limited transparency into model context, permission boundaries, or reproducibility across environments. That tradeoff works for many workflows, but it breaks down for infrastructure, backend, and compliance-heavy engineering.

A second tension is provider lock-in. In practice, model quality, cost, latency, legal terms, and data handling requirements all change over time. If your coding agent is hard-wired to a single vendor, your team inherits that vendor's pricing and roadmap decisions whether or not they fit your constraints. Teams with NDAs, private source, or regulated systems often need the ability to switch providers or run local inference without changing their workflow.

A third tension is operational reality. Many developers do not work in a single desktop IDE context all day. They work over SSH in remote Linux hosts, inside ephemeral CI runners, in locked-down enterprise laptops, or in Dockerized build systems. Tools that require a specific IDE plugin stack or runtime ecosystem are often awkward or impossible in those environments. Akmon was built for those constraints first, not as an afterthought.

The design decisions (and why)

Single binary

Akmon is compiled Rust, shipped as a standalone executable. This is not just "nice for install." It means predictable behavior across machines because there is no dependency on a host Node/Python runtime, global package manager state, or plugin version drift. If two machines run the same Akmon version, the agent behavior is far easier to reason about.

That portability matters in practical environments:

• local development on macOS,
• remote debugging over SSH on Debian/Ubuntu,
• containerized CI jobs with minimal base images,
• controlled or air-gapped environments where runtime bootstrap is tightly restricted.

When a tool's runtime stack is small and explicit, troubleshooting is also faster. A failed run is usually a model/provider issue, permission policy issue, or repository issue, not "works on my machine because npm state differed."

Bring your own key / bring your own model

Akmon supports Anthropic, OpenAI, OpenRouter, Groq, Azure OpenAI, Bedrock, OpenAI-compatible endpoints, and Ollama for offline local execution. You can select the model per task.

Why this matters:

• commercial control: you decide which provider's pricing and terms you accept,
• privacy control: with Ollama, code can remain local,
• resilience: if one provider is degraded or rate-limited, your workflow does not collapse,
• task fit: cheaper models for repetitive edits, stronger models for architecture/design.

In other words, model choice becomes an engineering decision, not a platform limitation.

Typed permission system

Tool execution is not free-form shell by default. Operations pass through permission checks modeled as typed actions (read file, write file, execute command, network fetch, and so on). The user can approve once, approve for a session, or deny based on policy and context.

That creates a concrete safety boundary between model suggestions and actual side effects. The model can request actions; it cannot silently mutate the system without policy passing those requests.

Audit log

Akmon can emit JSONL audit events with session metadata, policy decisions, tool calls, and execution flow. This is essential for teams that need post-run review and accountability.

Practically, it gives you answers to questions like:

• what command executed and when,
• what file was modified and after which approval,
• where the session stopped,
• what model and token usage were involved.

The point is not surveillance; the point is operational clarity when AI performs meaningful work on production code.

Context as architecture

Akmon's workflow emphasizes context discipline: research, plan/spec, then implementation. That structure exists because LLM performance degrades when context fills with stale exploration artifacts.

Instead of trying to keep one giant conversation forever, Akmon encourages:

1. focused exploration,
2. explicit plan/spec on disk (.akmon/specs),
3. implementation from plan with iterative verification.

This makes sessions more predictable, easier to resume, and less likely to drift into repetitive read loops.

Who Akmon is for

Backend developers working across varied environments

If you work in terminal-first repositories, remote hosts, and client-controlled systems where installing editor plugins is inconsistent, Akmon's single-binary model is a practical fit.

Platform and DevOps engineers automating changes

Headless mode (--task, --yes, --output json) is designed for automation and CI integration. Budget controls and structured outputs make it easier to gate and observe autonomous runs.

Regulated or privacy-constrained teams

Teams that need to constrain data movement can run local models with Ollama and keep a durable audit record for operational/compliance review.

Open-source maintainers avoiding vendor coupling

Akmon is Apache-2.0 and provider-agnostic. You can evolve model strategy over time without replacing the tool itself.

What Akmon does not do

Akmon is intentionally opinionated, and that includes explicit limits:

• It is not an IDE extension with inline completions and graphical diff UX.
• It does not try to out-polish provider-native tools in their own primary environment.
• Local models can be slower and less capable on complex multi-file design tasks.
• It is terminal-first and expected to remain that way.

Those are deliberate tradeoffs in favor of portability, policy boundaries, and scriptability.

Common mistakes and troubleshooting

Mistake: using one expensive model for every task

Use a cheaper model for exploration/refactors and reserve stronger models for architecture-heavy reasoning.

Mistake: skipping project context

Create and maintain AKMON.md. A short, high-quality project context usually improves outputs more than writing longer prompts each turn.

Mistake: running headless without budget limits

For CI and automation, use --max-budget-usd and parse --output json for safe exits.

Mistake: blaming model quality for policy friction

If the agent seems "stuck," inspect permission prompts and policy settings first. In many cases the model is waiting for explicit approval.

Where to go next

• Install and first run: Getting Started
• Practical walkthroughs: Step-by-step tutorials
• Automation and CI: Headless mode
• Integration with external systems: MCP guide
• Internal architecture for contributors: Contributing architecture

Akmon vs other coding agents

Most tools in this space are good. The real question is what tradeoffs fit your environment.

What Akmon optimizes for

Akmon is built for:

• terminal portability (single binary, SSH/CI friendly),
• provider independence (BYOK/BYOM),
• explicit permission boundaries for side effects,
• auditable execution traces.

It is not trying to replicate full IDE-native UX.

Comparison matrix

Common scenarios

Choose Akmon when

• you need to run in CI, remote shells, or locked-down environments,
• you need provider flexibility over time,
• your team requires clear policy and audit trails for AI side effects.

Choose IDE-first tools when

• your priority is inline coding UX and editor-native interaction speed.

Choose provider-native terminal tools when

• you are intentionally standardizing on one provider and want its most optimized interaction model.

Practical guidance

Many teams mix tools:

• use Akmon for automation, refactors, and auditable changes,
• use IDE tooling for day-to-day interactive editing.

The best stack is often hybrid, not exclusive.

Common mistakes

• Treating this as a winner-takes-all decision.
• Ignoring compliance and deployment constraints until late adoption.
• Evaluating only "response quality" and not operational fit (auditability, portability, budget controls).

← Introduction · Security model →

Tutorials overview

These tutorials are written for experienced developers who want production-style usage, not toy prompts.

Before you start

Complete:

• Installation
• Quick start
• optional provider setup for your preferred model

Recommended baseline command:

akmon --version

Learning path

Suggested order by role

Individual developer

1. step-by-step,
2. architecture-patterns,
3. multi-agent-automation.

Platform/DevOps engineer

1. step-by-step (one stack),
2. multi-agent-automation,
3. headless mode.

Maintainer handling large refactors

1. architecture-patterns,
2. step-by-step tutorial 4 (existing codebase refactor),
3. audit log.

Troubleshooting prerequisites

• If provider calls fail, verify keys and model names first.
• If sessions drift, create/update AKMON.md before continuing.
• If costs rise unexpectedly, use phased workflow and watch /context + /cost.

Related: language guides, plan mode, architect mode, headless mode.

Step-by-step: real workflows from zero to shipped

This page walks through four complete tutorials with concrete commands, expected outputs, common failures, and resulting files.

Tutorial 1: Rust + Axum REST API from scratch

Setup

mkdir -p ~/projects/bookshelf-api
cd ~/projects/bookshelf-api
git init
export ANTHROPIC_API_KEY=sk-ant-...
akmon chat

Create AKMON.md (via /init or manually):

# Bookshelf API

Rust + Axum + SQLite REST API for managing books.

## Stack
- Language: Rust 1.75+
- Framework: Axum 0.7
- Database: SQLite via rusqlite
- Auth: JWT with jsonwebtoken

## Conventions
- Error type: AppError implementing IntoResponse
- Database: connection pool via r2d2
- Verify: cargo check 2>&1 | head -20

Session flow

Prompts to send in order:

1. Initialize the project with Cargo.toml and basic dependencies
2. Create src/main.rs with Axum app bootstrap and health endpoint
3. Create src/models/book.rs with CRUD model operations
4. Create src/routes/books.rs with GET /books and POST /books
5. Wire routes into main and add minimal integration tests

What you should see:

• tool calls to write_file for Cargo.toml and src/*,
• permission dialog per write (press y once or s for session allowance),
• verification shell commands (cargo check) after write batches,
• final Done plus cost/token summary.

Expected output tree:

bookshelf-api/
  Cargo.toml
  src/
    main.rs
    error.rs
    routes/
      mod.rs
      books.rs
    models/
      mod.rs
      book.rs
  tests/
    books_api.rs

If something goes wrong

• cargo check fails: ask Fix compile errors only, no refactor.
• Agent loops on reads: ask Stop exploration and implement from current context.
• Rate limited: run akmon -c to continue.

Tutorial 2: Python FastAPI + PostgreSQL

Setup

mkdir -p ~/projects/users-api
cd ~/projects/users-api
git init
python -m venv .venv
source .venv/bin/activate
akmon chat

Use explicit 3-phase flow:

1. Research: Explore this repo and propose FastAPI + SQLAlchemy layout
2. Plan: /plan then Write a step-by-step implementation plan
3. Implement: /implement

Prompt examples:

• Create pyproject.toml, app entrypoint, and dependency set
• Add SQLAlchemy models for users table and repository layer
• Add FastAPI routers for GET /users and POST /users
• Add pytest tests for validation and database behavior

Expected files:

users-api/
  pyproject.toml
  app/
    main.py
    db.py
    models.py
    schemas.py
    repository.py
    routes/users.py
  tests/
    test_users.py

Troubleshooting:

• DB connection error: provide a local DATABASE_URL in .env.
• pytest import errors: ask agent to fix Python path/package init files only.

Tutorial 3: TypeScript/Next.js full-stack app

Setup

mkdir -p ~/projects/notes-web
cd ~/projects/notes-web
git init
akmon chat --model anthropic/claude-haiku-4-5

Use architect mode for split reasoning:

akmon --architect \
  --planner-model llama3.2 \
  --model anthropic/claude-haiku-4-5 \
  --task "Create a Next.js notes app with API routes and sqlite persistence"

What this demonstrates:

• planner creates architecture first,
• implementer executes files in focused steps,
• context remains cleaner than one long free-form run.

Expected files:

notes-web/
  package.json
  app/
    page.tsx
    api/notes/route.ts
  lib/
    db.ts
    notes.ts
  tests/
    notes.test.ts

Troubleshooting:

• Type errors: ask Run tsc and fix only reported errors.
• Next route mismatch: ask Align route handler signatures with Next version in package.json.

Tutorial 4: Refactoring an existing codebase

Setup

cd ~/projects/existing-service
akmon --plan --task "Analyze auth module and propose OAuth migration plan"

Then:

1. review generated plan,
2. run implementation in focused steps,
3. continue with akmon -c if interrupted/rate-limited.

Recommended prompts:

• Implement step 1 only from the plan; run tests
• Implement next unchecked step and verify
• Summarize changed files and remaining plan items

Audit review:

ls .akmon/audit/
jq . .akmon/audit/<latest>.jsonl | head -40

What you should see:

• policy decisions per write/shell call,
• tool outputs tied to each step,
• clear trail of refactor sequence.

Common mistakes

• Asking for "build everything" in one turn.
• Missing AKMON.md conventions (verification commands, architecture boundaries).
• Running in headless mode without budget limits.

Next steps

• Multi-agent patterns: multi-agent automation
• Headless CI workflows: headless mode
• Project context quality: AKMON.md guide

Multi-agent automation in practice

Multi-agent in Akmon means decomposing work into multiple focused sessions instead of one giant context-heavy loop.

The problem with single-agent sessions

If you ask one session to both explore and implement a large subsystem, context fills with stale file reads and old reasoning. By the time code generation starts, the model is paying token/cognitive budget for irrelevant history.

Typical failure pattern:

1. reads 10-20 files,
2. repeats exploration because context is noisy,
3. implementation quality drops,
4. token cost rises.

How spawn_subagent helps

A subagent run is a fresh focused session. It performs exploration and returns a compact summary to the main session. The main implementation session does not carry every exploratory file read in its context.

Net effect:

• smaller implementation context,
• fewer repeated reads,
• clearer plan/spec handoff,
• lower token waste.

Three-phase pattern

Phase 1: Research (subagent)

Goal: understand codebase boundaries and constraints.

Prompt:

Explore authentication flow and summarize entry points, middleware, data models, and tests. Return only structured findings.

Phase 2: Specification (main session)

Goal: persist plan to disk.

akmon --plan --task "Write implementation plan for OAuth integration using research summary"

Creates .akmon/specs or plan artifacts that survive compaction/restart.

Phase 3: Implementation (main session)

Goal: execute one checked step at a time with verification.

Prompt style:

Implement step 1 only, run verification commands, then stop.

Repeat for each step.

Real example: adding a payment system

Research prompt:

Find existing payment-related code, billing models, and webhook endpoints. Summarize what exists and what is missing.

Plan file example:

# Plan: Stripe Payment Integration

## Research findings
- Current payment code: none
- User model in src/models/user.rs has email field
- API is Axum with JWT auth in src/middleware/auth.rs

## Implementation steps
- [ ] Add stripe dependency to Cargo.toml
- [ ] Create src/payments/mod.rs with Stripe client setup
- [ ] Create src/payments/checkout.rs with create_session
- [ ] Create src/payments/webhook.rs with event handling
- [ ] Add POST /payments/checkout route
- [ ] Add POST /payments/webhook route
- [ ] Add payment_status to user model
- [ ] Write integration tests

Implementation run:

Implement the next unchecked payment step. Run tests relevant to touched files.

Parallel research strategy for large monorepos

For very large repositories:

1. run multiple research tasks by domain (auth, billing, API, infra),
2. produce short summaries per domain,
3. merge into one implementation plan.

This is more reliable than one massive exploratory session.

Common mistakes and troubleshooting

• Skipping written plan: always persist to spec/plan before implementation.
• Research summary too verbose: ask for bullet-point outputs with file paths only.
• Main session still bloated: reset implementation session and re-run from plan.
• Unclear ownership in automation: assign per-phase prompts and expected outputs explicitly.

Architecture patterns for agent-assisted development

Akmon does not dictate your system architecture—it documents and executes against the architecture you describe. These patterns work well in practice.

Single repo, single source of truth (AKMON.md)

When: Small teams, one deployable.

How:

• Maintain Product, Architecture, Conventions, Current sprint in AKMON.md (reference).
• Run akmon --plan before refactors that touch many modules.
• Use /update-context in the TUI when editing AKMON.md mid-session.

Risk: Drift if nobody updates Current sprint—treat it like a stand-up note.

Planner / implementer split

When: Expensive frontier models, or you want cheap exploration before precise edits.

How:

• Architect mode: planner model writes a plan file, main model implements.
• Or manual: --plan + review + --yes --task.

Risk: Plans can go stale; re-run plan if main branch moved.

Spec-driven (requirements → design → tasks)

When: New features with unclear scope; need written artifacts for review.

How: Spec workflow — akmon spec … phases under .akmon/specs/.

Risk: More ceremony; best when the spec is genuinely reviewed by humans.

Automation + human gate

When: Nightly hygiene (formatters, comment sweeps) without full write access in CI.

How:

• Narrow --task in automation; require PR for merges.
• Keep destructive operations out of unattended jobs.

Risk: Broad tasks in --yes can still surprise you—scope tightly.

Multi-service repos (monorepo)

When: Several services share conventions.

How:

• One AKMON.md at root with Architecture mapping services; or per-service nested guides linked from root.
• Run Akmon from the service subdirectory when the sandbox should be minimal.

Risk: Wrong working directory → wrong paths; always cd to the intended git root.

Documentation as contract

When: Regulated or long-lived systems.

How:

• Commit plans under .akmon/plans/ as part of the change record.
• Export audit JSONL to your retention system.

Risk: Treat plans as non-authoritative unless your process says otherwise—they are agent output, not legal sign-off.

Choosing a pattern

Installation

Requirements

• Git — for project context and git operations
• Rust 1.88+ — only if building from source
• Ollama — optional, for local offline models

Option 1 — Pre-built binary (recommended)

Releases on GitHub include akmon-darwin-arm64, akmon-darwin-x86_64, and akmon-linux-x86_64. They are slim builds (--no-default-features, no bundled semantic index).

Install without sudo (recommended)

Put the binary in ~/bin and ensure it is on your PATH:

macOS — Apple Silicon

mkdir -p ~/bin
curl -fsSL -L https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-darwin-arm64 \
  -o ~/bin/akmon && chmod +x ~/bin/akmon

macOS — Intel

mkdir -p ~/bin
curl -fsSL -L https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-darwin-x86_64 \
  -o ~/bin/akmon && chmod +x ~/bin/akmon

Linux — x86_64

mkdir -p ~/bin
curl -fsSL -L https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-linux-x86_64 \
  -o ~/bin/akmon && chmod +x ~/bin/akmon

Shell PATH (zsh example) — if akmon is not found:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Install to /usr/local/bin (needs admin)

sudo curl -fsSL -L https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-darwin-arm64 \
  -o /usr/local/bin/akmon && sudo chmod +x /usr/local/bin/akmon

(Use the correct asset name for your platform.)

Troubleshooting downloads

Verify

akmon --version
# e.g. akmon 1.7.0

Option 2 — From source

git clone https://github.com/radotsvetkov/akmon
cd akmon

# Slim build — no semantic indexing, smaller binary
cargo build --release --no-default-features

# Full build — with semantic indexing
cargo build --release

mkdir -p ~/bin
cp target/release/akmon ~/bin/

Option 3 — cargo install

cargo install akmon

Using over SSH

Akmon is a single static binary. Copy it to any remote machine:

scp ~/bin/akmon user@remote:~/bin/
ssh user@remote
export PATH="$HOME/bin:$PATH"
akmon chat

Using in Docker

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
  && rm -rf /var/lib/apt/lists/* \
  && curl -fsSL -L \
  https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-linux-x86_64 \
  -o /usr/local/bin/akmon && chmod +x /usr/local/bin/akmon
WORKDIR /workspace
ENTRYPOINT ["akmon"]

Using in CI

# GitHub Actions example
- name: Install Akmon
  run: |
    sudo curl -fsSL -L https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-linux-x86_64 \
      -o /usr/local/bin/akmon && sudo chmod +x /usr/local/bin/akmon

- name: Run task
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    akmon --yes --output json \
      --task "run tests and summarize failures" \
      | jq .result

Uninstalling

rm -f ~/bin/akmon /usr/local/bin/akmon
rm -rf ~/.akmon   # removes config, sessions, audit logs

Quick Start

From zero to a working AI coding session in under 5 minutes.

Step 1 — Choose a model provider

Local (free, private, offline)

Install Ollama and pull a model:

ollama pull qwen2.5-coder:7b

Akmon detects Ollama automatically. No key needed.

Cloud API

# Anthropic — best quality
export ANTHROPIC_API_KEY=your-key

# OpenRouter — 500+ models with one key
export OPENROUTER_API_KEY=your-key

# Groq — fastest inference
export GROQ_API_KEY=your-key

Step 2 — Open your project

cd your-project
akmon chat

The TUI opens. If this is your first session in this project, Akmon suggests running /init to generate project memory.

Step 3 — Try your first task

Type a task in plain language and press Enter:

explain how authentication works in this codebase

Akmon will search the codebase semantically, read relevant files, and explain what it found.

Step 4 — Make a change

add input validation to the create_user function

Before writing any file, Akmon shows a colored diff of exactly what will change. You approve or reject each change.

Step 5 — Generate project memory

/init

Akmon analyzes your project and generates AKMON.md — a context file describing your tech stack, conventions, and architecture. Every session after this will produce better results.

Common first tasks

Key slash commands

Exit summary

When you exit, Akmon shows a full session summary:

  Akmon session complete

  Session
  ──────────────────────────────────
  ID         a1b2c3d4
  Duration   12m 34s
  Directory  ~/my-project
  Model      claude-haiku-4-5 (Anthropic)

  Activity
  ──────────────────────────────────
  Messages      14
  Tool calls    23
    ✓ Succeeded  22
    ✗ Failed      1
  Files read    8
  Files written 3

  Tokens
  ──────────────────────────────────
  Input      48,291
  Output      6,847
  Cache hit  41,203 (85% savings)
  Est. cost  ~$0.047

  Audit log
  ──────────────────────────────────
  .akmon/audit/a1b2c3d4.jsonl

  Agent powering down. Goodbye!

Configuration

Akmon reads settings from ~/.akmon/config.toml and environment variables. CLI flags override both.

Config wizard

akmon config

With no subcommand, Akmon runs a short interactive questionnaire on stdin: default model, optional Anthropic / OpenRouter keys, and Ollama base URL. It writes ~/.akmon/config.toml (and may append .akmon/ to .gitignore when you store an Anthropic key).

• For automation or JSON output, pass an explicit subcommand. akmon config --json requires a subcommand (for example akmon config show --json) so stdout stays machine-readable.
• Everything the wizard sets can also be configured with akmon config <topic> …, by editing TOML, or via environment variables (see Environment variables).

Fullscreen TUI and scrollback

The default chat UI uses the terminal’s alternate screen, so your emulator’s normal scrollback may not include the full conversation. Use the /transcript slash command to write the current chat to .akmon/transcript_export.md in the project, then open it in less, an editor, or a pager.

Show effective config

akmon config show

Sensitive values are masked in output.

config.toml location

Project-level overrides may apply depending on your setup; use akmon config path to see which file is active.

Common keys

Typical [model] section:

[model]
default = "claude-haiku-4-5-20251001"
anthropic_key = "sk-ant-..." # prefer: akmon config key set

[architect]
planner_model = "llama3.2"

For OpenRouter:

[model]
default = "anthropic/claude-haiku-4-5"
openrouter_key = "sk-or-..."

Model context window and cost estimate ([model_estimates])

The TUI’s context % bar reflects model context window usage from reported token counts. Rate limits (requests/minute, tokens/minute, spend caps) are enforced by your provider and are independent of that percentage—you can be low on context and still hit a limit.

Akmon’s USD session cost is a rough estimate from usage tokens and optional price tables (not a bill from your provider).

Optional rows match the current model id (substring match, first match wins). If you omit context_window_tokens, a built-in hint may still apply for common ids.

In the TUI, use /config (or Ctrl+S) → Estimates to edit these fields for the current model without hand-editing TOML.

[[model_estimates]]
pattern = "haiku-4-5"
context_window_tokens = 200_000
# Optional: USD per 1M tokens (override built-in defaults when you know list pricing)
input_per_million_usd = 1.0
output_per_million_usd = 5.0
cache_read_per_million_usd = 0.1
# Shown in /context as a reminder (not enforced by Akmon)
note = "Check Anthropic console for RPM/TPM and tier limits."

The same table is used by the headless CLI for cost accumulation. Changes saved from the TUI apply immediately; if you edit config.toml by hand, restart Akmon to pick them up.

Editor integration

Set EDITOR (or rely on the default) for /edit-plan and /update-context in the TUI:

export EDITOR="nvim"

See also Environment variables and Configuration reference.

Provider Setup

Choosing a provider

Ollama

No API key needed:

# Install from https://ollama.com
ollama pull qwen2.5-coder:7b   # recommended for code
ollama pull llama3.2            # faster, lighter
ollama pull deepseek-coder-v2   # excellent for code

akmon chat  # auto-detects Ollama
akmon chat --model qwen2.5-coder:7b  # explicit

Anthropic

export ANTHROPIC_API_KEY=sk-ant-...

akmon chat --model claude-haiku-4-5-20251001  # fast, cheap
akmon chat --model claude-sonnet-4-6          # balanced
akmon chat --model claude-opus-4-6            # best quality

OpenRouter

One key, 500+ models, automatic failover:

export OPENROUTER_API_KEY=sk-or-...

# Model format: "provider/model-name"
akmon chat --model anthropic/claude-haiku-4-5
akmon chat --model meta-llama/llama-3.3-70b-instruct
akmon chat --model deepseek/deepseek-chat
akmon chat --model google/gemini-2.0-flash

Groq

export GROQ_API_KEY=gsk_...
akmon chat --model llama-3.3-70b-versatile
akmon chat --model llama-3.1-8b-instant   # extremely fast

OpenAI

export OPENAI_API_KEY=sk-...
akmon chat --model gpt-4o
akmon chat --model gpt-4o-mini

Azure OpenAI

akmon chat \
  --azure-endpoint https://your-resource.openai.azure.com/openai/deployments/your-deployment \
  --azure-key your-key \
  --model gpt-4o

Amazon Bedrock

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1

akmon chat --bedrock \
  --model anthropic.claude-haiku-4-5-v1:0

Supported Bedrock models (examples — check AWS for current list):

• anthropic.claude-haiku-4-5-v1:0
• anthropic.claude-sonnet-4-6-v1:0
• anthropic.claude-opus-4-6-v1:0
• meta.llama3-8b-instruct-v1:0
• meta.llama3-70b-instruct-v1:0

Custom OpenAI-compatible endpoint

LM Studio, Mistral, Together AI, or any OpenAI-compatible API:

akmon chat \
  --openai-compatible-url http://localhost:1234/v1 \
  --model your-model-name

Saving configuration

Use the config wizard instead of setting env vars every session:

akmon config

Or set in ~/.akmon/config.toml:

[model]
default = "claude-haiku-4-5-20251001"
anthropic_key = "sk-ant-..."

# Or for OpenRouter:
# default = "anthropic/claude-haiku-4-5"
# openrouter_key = "sk-or-..."

Per-provider pages: Ollama, Anthropic, and the rest under Providers in the sidebar.

Interactive mode

Interactive mode is the default way to work with Akmon when you want close control over prompts, permissions, and step-by-step execution.

akmon chat

What the UI is showing you

The TUI is designed around operational awareness:

• conversation transcript and tool calls,
• approval prompts for side effects,
• session/provider/model identity,
• context/token/cache/cost signals.

It is not just chat; it is a control surface for autonomous execution.

Typical interaction pattern

1. give focused task,
2. review tool calls and approvals,
3. inspect diffs before writes,
4. run verification commands,
5. iterate until completion.

Example starting prompt:

Add input validation to user registration, update tests, and run verification commands after each file change.

Status and context indicators

Key footer/top indicators usually include:

• session id,
• model/provider,
• cumulative input/output tokens,
• cache read tokens,
• cost estimate,
• context usage bar/percentage.

For long runs, monitor context percentage and compact/reset before quality drifts.

Slash commands that matter most

• /model switch model mid-session,
• /plan create plan-only turn,
• /context view context budget and thresholds,
• /cost inspect usage/cost breakdown,
• /copy copy latest assistant response.

Approval flow

When the model requests writes or command execution:

1. inspect proposed action/diff,
2. approve once or for session where appropriate,
3. deny if scope drifts.

Use session-wide allowances carefully; they trade control for speed.

Common mistakes and troubleshooting

• Mistake: broad vague prompts ("fix everything").
  • Fix: split by subsystem and expected verification.
• Mistake: ignoring context/cost indicators in long sessions.
  • Fix: use /context and continue in focused phases.
• Mistake: approving shell writes blindly.
  • Fix: check command intent and command scope before allow.

See also slash commands, plan mode, and headless mode.

Headless mode

Headless mode runs Akmon without interactive supervision and is ideal for CI/CD, scripted maintenance, and batch repository automation.

When to use headless mode

Use headless mode when you need repeatable automated execution:

• pull-request checks,
• scheduled maintenance tasks,
• org-wide refactoring runs,
• scriptable JSON output for downstream tooling.

Basic command pattern

akmon \
  --model claude-haiku-4-5-20251001 \
  --yes \
  --max-budget-usd 2.00 \
  --output json \
  --task "Run cargo clippy and fix warnings without changing behavior"

Complete GitHub Actions example

name: AI-powered lint fix

on:
  pull_request:
    types: [opened]

jobs:
  ai-fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Akmon
        run: |
          curl -L https://github.com/radotsvetkov/akmon/releases/latest/download/akmon-linux-x86_64.tar.gz | tar xz
          sudo mv akmon /usr/local/bin/

      - name: Run Akmon
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          akmon \
            --model claude-haiku-4-5-20251001 \
            --yes \
            --max-budget-usd 2.00 \
            --output json \
            --task "Run cargo clippy and fix warnings. Run cargo test after each change." \
          | tee akmon-result.json

      - name: Check exit
        run: |
          status=$(jq -r '.exit_reason' akmon-result.json)
          test "$status" = "completed"

JSON output fields

Typical run report:

{
  "session_id": "d329615d-...",
  "status": "completed",
  "exit_reason": "completed",
  "result": "Fixed 14 clippy warnings across 6 files",
  "tool_calls": 28,
  "files_written": ["src/main.rs", "src/auth.rs"],
  "usage": {
    "total_input_tokens": 145000,
    "total_output_tokens": 8200,
    "total_cache_read_tokens": 98000
  },
  "cost_usd": 0.18
}

Practical interpretation:

• exit_reason gates CI behavior,
• files_written can trigger selective test/deploy logic,
• usage and cost_usd feed budget reporting.

Budget control in production

Recommended patterns:

• per-run cap: --max-budget-usd 1.00,
• fail CI when exit_reason != completed,
• aggregate daily spend via scheduled job reading JSON outputs.

Example shell budget gate:

result=$(akmon --yes --output json --max-budget-usd 1.5 --task "...")
cost=$(echo "$result" | jq -r '.cost_usd')
echo "run cost: $cost"

Batch processing multiple repositories

#!/usr/bin/env bash
set -euo pipefail

repos=(
  ~/services/auth-service
  ~/services/payment-service
  ~/services/notification-service
)

for repo in "${repos[@]}"; do
  echo "Processing $repo"
  cd "$repo"
  result=$(akmon \
    --model claude-haiku-4-5-20251001 \
    --yes \
    --max-budget-usd 3.00 \
    --output json \
    --task "Update dependencies to latest compatible versions and run tests")
  echo "$result" | jq -r '"\(.session_id) \(.exit_reason) $\( .cost_usd )"'
done

Common mistakes and troubleshooting

• No budget cap: always set --max-budget-usd in unattended runs.
• Overly broad task: split "fix everything" into narrower tasks.
• Missing provider key in CI: verify env injection before run.
• Non-zero exit from incomplete runs: parse exit_reason, do not assume success from process completion alone.

Plan mode

Plan mode performs read-only analysis and produces implementation plans without changing files.

akmon --plan --task "your task"

Why plan mode exists

Large tasks fail when implementation starts before scope is understood. Plan mode separates discovery from execution:

1. map relevant files and constraints,
2. produce ordered implementation steps,
3. define verification per step,
4. execute later with lower risk.

What is allowed in plan mode

• read/list/search tools,
• optional semantic search when enabled,
• no write/edit/patch tool registration.

This is structural read-only behavior, not just "please don't write."

Recommended workflow

akmon --plan \
  --model claude-haiku-4-5-20251001 \
  --task "Design migration from sqlite auth sessions to redis-backed sessions with rollback strategy"

Then:

ls .akmon/plans
$EDITOR .akmon/plans/<latest>.md
akmon --task "Implement the approved plan in .akmon/plans/<latest>.md step by step"

What a good plan should contain

• target files/modules,
• ordered steps,
• risk notes and migration impact,
• verification commands after each step,
• rollback hints.

TUI usage

• run /plan,
• submit task,
• review plan,
• run /implement when approved.

Common mistakes and troubleshooting

• Mistake: skipping plan review before implementation.
• Mistake: one giant implementation step instead of checkpoints.
• Mistake: missing verification commands in plan.

Plan mode pairs naturally with architect mode and spec workflow.

Architect mode

Architect mode runs a planner phase and implementation phase in one command.

Why use architect mode

It is useful when you want:

• cheap/fast planning model,
• stronger implementation model,
• less manual handoff between plan and execution.

Basic command

akmon --architect \
  --planner-model llama3.2 \
  --model claude-haiku-4-5-20251001 \
  --task "Refactor database layer to use connection pooling with migration-safe rollout"

How the phases differ

Practical model strategy

• use low-cost local/cloud model for planning,
• use Haiku/Sonnet-class model for implementation complexity,
• reserve expensive models for hard reasoning bottlenecks.

Suggested usage pattern

1. run architect command,
2. inspect generated plan artifacts,
3. review first implementation diff before broad approvals,
4. continue in focused increments.

Common mistakes and troubleshooting

• Mistake: planner model too weak to map architecture.
  • Fix: upgrade planner model for complex repos.
• Mistake: no budget cap in long implement phases.
  • Fix: combine with --max-budget-usd.
• Mistake: skipping post-plan review.
  • Fix: verify plan assumptions before writes.

Related: plan mode, headless mode, configuration.

Spec Workflow

For building new features from scratch with structured planning. Three phases: requirements → design → tasks → implementation.

Overview

# Phase 1: Generate requirements
akmon spec auth-system "JWT authentication with refresh tokens"

# Phase 2: Generate technical design (after reviewing requirements)
akmon spec auth-system design

# Phase 3: Generate implementation tasks
akmon spec auth-system tasks

# Implement one task at a time
akmon spec auth-system implement

Artifacts live under .akmon/specs/<name>/.

Phase 1 — Requirements

akmon spec payment-flow \
  "Stripe payment integration with webhook handling \
   and subscription management"

Produces .akmon/specs/payment-flow/requirements.md with user stories, acceptance criteria, scope, and open questions.

Phase 2 — Design

akmon spec payment-flow design

Reads requirements.md, analyzes the codebase, and writes design.md with architecture, new components, modified files, and data flow.

Phase 3 — Tasks

akmon spec payment-flow tasks

Writes tasks.md with checkboxes, dependencies, and sized work items.

Implementation

akmon spec payment-flow implement

Akmon picks the first unchecked task, implements it, checks it off, and stops for human review. Re-run for the next task.

This human-in-the-loop per task pattern limits runaway changes that drift from the spec.

See also

• CLI reference for exact akmon spec syntax and flags.

akmon init

Analyzes your project and generates AKMON.md — structured project memory used in every session.

Usage

cd your-project
akmon init

• Detects stack (languages, frameworks, tooling).
• Writes or updates AKMON.md with product context, architecture, conventions, and sprint sections.
• If other tools already left context files (CLAUDE.md, .cursorrules, …), you can run akmon import first to synthesize them into AKMON.md.

Why run it

Sessions with AKMON.md get better, more consistent answers because the model sees your conventions upfront.

TUI

In akmon chat:

/init

Same operation from inside the interactive UI.

See also

• AKMON.md reference
• Importing context

AKMON.md guide

AKMON.md is the highest-leverage file in an Akmon project. It is loaded at session start and continuously influences planning, tool selection, and verification behavior.

Why AKMON.md matters more than a one-off prompt

Prompts are ephemeral. AKMON.md is persistent and reused every run. If you encode architecture boundaries and verification commands in this file, the agent can follow them automatically across turns and sessions.

Examples:

• if AKMON.md says verify: cargo check 2>&1 | head -20, the agent tends to run that after edits,
• if it says repository pattern only, the agent is less likely to generate active-record style shortcuts,
• if it says no unwrap() in library crates, reviews and fixes stay aligned.

Anatomy of an effective AKMON.md

Use concise sections:

• Product: what this project does and key constraints,
• Architecture: module boundaries and forbidden dependencies,
• Conventions: code style, error handling, naming, test policy,
• Verification: canonical commands per change type,
• Current sprint: immediate goals and priorities.

Example: Rust service

# Payment Service

Stripe payment processing microservice.
Rust 1.75 + Axum 0.7 + PostgreSQL + SQLx.

## Architecture
- domain/: pure business logic
- ports/: trait interfaces
- adapters/: db/http/stripe implementations
- application/: orchestration layer

Never import adapters into domain.

## Error handling
Use thiserror in domain, anyhow in orchestration.

## Verification
After Rust file: cargo check 2>&1 | head -20
After business logic: cargo test domain 2>&1
After handlers: cargo test integration 2>&1

Example: Python FastAPI

# User Analytics API

FastAPI + PostgreSQL + Redis event tracking.

## Layout
src/api/routes/
src/services/
src/repositories/
src/models/
src/schemas/

## Conventions
- routes -> services -> repositories
- no direct repository calls from routes
- strict schema validation

## Verification
After Python file: python -m py_compile {file}
After models: alembic check
After routes: pytest tests/api/ -x -q

The 2000-character rule

AKMON.md appears in many model calls. Oversized context inflates recurring input tokens and reduces room for live task reasoning.

Practical guideline:

• target <= 2000 characters,
• keep durable details in AKMON.md,
• move long implementation plans into .akmon/specs/*.md.

Maintenance workflow

1. initialize or refresh with akmon init,
2. edit manually or via /update-context,
3. review after major architecture changes,
4. keep Current sprint up to date.

Common mistakes and troubleshooting

• Too vague: "clean code, best practices" is not actionable.
• Too long: giant prose blocks are expensive and low signal.
• Missing verification commands: agent cannot infer your CI expectations reliably.
• Stale sprint section: leads to drift and irrelevant actions.

Importing Context

If you have been using another AI coding tool, your project may already have context files. Akmon can synthesize them into AKMON.md.

Supported tools

Basic usage

cd your-project
akmon import

Akmon scans context files and uses your configured model to build AKMON.md.

Preview without writing

akmon import --dry-run

Import from a specific tool only

akmon import --from claude-code
akmon import --from cursor
akmon import --from kiro

Overwrite existing AKMON.md

akmon import --force

In the TUI

When no AKMON.md exists, the welcome screen may suggest /import. Run it to perform the same synthesis from inside akmon chat.

See also

• Export
• AKMON.md reference

Exporting Context

Export AKMON.md to native formats for other AI tools — useful for teams using mixed workflows.

Export to all tools

akmon export --all

Typical outputs include CLAUDE.md, AGENTS.md, .cursor/rules/akmon.mdc, .kiro/steering/akmon.md, Copilot instructions, Windsurf rules, Cline rules, etc. (exact set follows the CLI help for your version).

Export to a specific tool

akmon export --tool claude-code   # → CLAUDE.md
akmon export --tool codex         # → AGENTS.md
akmon export --tool cursor        # → .cursor/rules/akmon.mdc
akmon export --tool kiro          # → .kiro/steering/akmon.md
akmon export --tool gemini        # → GEMINI.md
akmon export --tool copilot       # → .github/copilot-instructions.md
akmon export --tool windsurf      # → .windsurfrules
akmon export --tool cline         # → .clinerules

Preview without writing

akmon export --all --dry-run

Workflow for multi-tool teams

1. Maintain AKmon.md as the single source of truth.
2. Run akmon export --all after meaningful updates.
3. Commit exports alongside AKMON.md if your team wants them in-repo.

Exported files should carry a banner like:

<!-- Generated from AKMON.md by Akmon -->
<!-- Edit AKMON.md, then run: akmon export --tool claude-code -->

See also

• Import

Rust Projects

Akmon detects Rust projects from Cargo.toml and applies Rust-oriented conventions and framework hints via the project intelligence layer.

Auto-detection

When Akmon finds Cargo.toml:

• Language profile Rust
• Workspace members when present
• Framework hints from dependencies (axum, actix-web, tokio, sqlx, diesel, ratatui, clap, tauri, bevy, …)

Conventions (steering)

Typical guidance injected for Rust codebases:

• thiserror for library errors, anyhow for application binaries (where appropriate)
• Avoid .unwrap() in production paths
• Prefer borrowing over unnecessary clones
• Document public items (rustdoc)
• Use spawn_blocking for CPU-heavy work inside async runtimes

Framework-specific notes (e.g. Axum handlers thin → services; SQLx query! and pools) are added when dependencies match.

Example: plan an Axum API

cargo new my-api && cd my-api
# add axum, tokio, sqlx, serde, thiserror, anyhow …
akmon --plan \
  --task "build a REST API with user authentication,
  PostgreSQL via SQLx, JWT tokens,
  layered architecture (handler → service → repository),
  and proper error handling"

Then implement when satisfied with the plan.

Example: explore a workspace

cd my-workspace
akmon chat

explain how akmon-core relates to akmon-tools
and what the data flow is between crates

Common Rust tasks

See Semantic search for --index usage on large Rust trees.

Python Projects

Akmon detects Python projects from pyproject.toml, requirements.txt, or setup.py.

Auto-detection

Framework hints may include:

• FastAPI, Django, Flask
• Pandas / Polars
• Scrapy, Celery
• PyTorch / HuggingFace

Conventions (steering)

Typical guidance:

• Type hints on public functions
• Pydantic v2 at API boundaries where applicable
• pathlib over os.path
• Context managers for resources
• No bare except:

Example: FastAPI service

mkdir my-api && cd my-api
uv init
uv add fastapi uvicorn sqlalchemy asyncpg pydantic alembic
akmon init
akmon --plan --task "build a FastAPI service with JWT auth,
SQLAlchemy async + PostgreSQL, Alembic migrations,
Pydantic v2 schemas, APIRouter per domain"

Example: Django performance

the order listing page is slow. analyze ORM queries
and fix N+1 issues with select_related / prefetch_related

Common Python tasks

TypeScript Projects

Akmon detects TypeScript from tsconfig.json and frameworks from package.json dependencies.

Auto-detection

• Next.js (App Router patterns)
• React
• NestJS
• Prisma, Drizzle, tRPC, Hono

Conventions (steering)

• strict: true
• Avoid any — prefer unknown + narrowing
• Zod (or similar) at API boundaries
• Path aliases instead of deep relative imports
• Discriminated unions for state machines

Example: Next.js

npx create-next-app@latest my-app --typescript --app
cd my-app
akmon init

add authentication with your chosen stack (e.g. auth library + DB)
using Server Actions where appropriate

Common TypeScript tasks

Go Projects

Akmon detects Go projects from go.mod and frameworks from module requirements.

Auto-detection

• Gin, Echo, Chi, Fiber
• Cobra CLIs
• GORM, sqlc, ent
• errgroup patterns

Conventions (steering)

• Check every error; never silently discard with _
• Accept interfaces, return concrete types
• context.Context first on I/O boundaries
• Table-driven tests with t.Run

Example: Gin API

mkdir my-api && cd my-api
go mod init example.com/my-api
go get github.com/gin-gonic/gin gorm.io/gorm gorm.io/driver/postgres
akmon init
akmon --plan --task "REST API for a blog with Gin, GORM + Postgres,
JWT middleware, handler → service → repository layout"

Common Go tasks

Other Languages

Akmon includes profiles beyond Rust, Python, TypeScript, and Go — for example JavaScript, Java, C#, Elixir, Swift, Kotlin, Dart, C++, Zig, and more. Detection uses manifests (pom.xml, *.csproj, mix.exs, Package.swift, pubspec.yaml, …).

JavaScript (no tsconfig.json)

Conventions steer toward ES modules, const/let, modern syntax, and async/await.

Java

Spring / Quarkus / Micronaut hints: records for DTOs, constructor injection, Optional, try-with-resources.

C#

ASP.NET Core: nullable reference types, records, async all the way through.

Elixir

Phoenix / LiveView: contexts, supervisors, {:ok, _} / {:error, _} tuples.

Swift / iOS

SwiftUI patterns, async/await, avoiding force unwraps in production paths.

Kotlin / Android

Compose-first guidance, coroutines, data classes.

Dart / Flutter

const constructors, separation of UI and logic, common routing libraries.

Run akmon init so AKMON.md captures stack-specific conventions your team cares about beyond auto-detection.

Example: REST API with Rust + Axum

End-to-end pattern: plan → scaffold → implement in layers → test.

Prerequisites

• Rust toolchain (see Installation)
• PostgreSQL (local or Docker)
• Provider API key or Ollama

Scaffold

cargo new blog-api && cd blog-api

Add dependencies (axum, tokio, sqlx, serde, thiserror, tower-http, tracing, auth crates, …) to Cargo.toml.

Plan

akmon --plan --task "blog REST API: register/login, JWT middleware,
CRUD posts, SQLx + Postgres pool, layered handlers,
custom ApiError as IntoResponse, GET /health"

Review .akmon/plans/*.md before implementation.

Implement incrementally

Typical sequence:

1. error.rs — error types + IntoResponse
2. state.rs — shared PgPool
3. Repositories / services
4. Routes + integration tests (sqlx::test)

akmon --yes --task "implement error + state modules from the plan"
akmon --task "implement repositories and handlers per plan"

Run

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16
export DATABASE_URL=postgres://postgres:postgres@localhost/blog_api
sqlx database create && sqlx migrate run
cargo run

Follow-ups

add cursor-based pagination to GET /posts

add utoipa OpenAPI spec and Swagger UI

Example: CLI tool with Python

Typer + Rich + Pydantic is a solid stack for user-friendly CLIs.

Setup

mkdir my-cli && cd my-cli
uv init
uv add typer rich pydantic httpx

Plan

akmon --plan --task "CLI for GitHub repo stats: stats OWNER/REPO,
compare REPO1 REPO2, trending [lang]. Typer + Rich tables,
Pydantic models for API JSON, httpx async client,
config file under ~/.config/my-cli/"

Implement

akmon --yes --task "implement the CLI per the saved plan"

Follow-ups

add JSON output mode for scripting

add shell completions via Typer

Python web services — Flask & FastAPI

This example complements the Python language guide and the step-by-step tutorial.

What you will demonstrate

• A read-only plan for a small API change (akmon --plan).
• A single headless implementation pass (akmon --yes) with tests.
• AKMON.md steering for framework-specific layout (app factory vs main.py, router modules, etc.).

Flask — readiness endpoint

Context in AKMON.md: Document how the app is created (create_app), where config lives, and the test command (pytest).

akmon --plan --task "Add GET /api/ready that returns {status: ok} and optionally verifies DB with existing engine"
akmon --yes --task "Implement /api/ready per the latest plan; use application factory pattern already in repo"
pytest

FastAPI — authenticated route

Context: List dependencies used for auth (e.g. OAuth2PasswordBearer, custom get_current_user).

akmon --plan --task "Add GET /users/me using existing JWT dependency; specify files to edit"
akmon --yes --task "Implement /users/me; mirror error handling from similar routes; add async tests"
pytest

Tips

• Put one test command in Conventions so every session agrees on verification.
• If you use OpenAPI, mention where the spec is generated—helps the agent avoid duplicate route definitions.
• For long handlers, prefer plan mode first so file boundaries are explicit before writes.

See also: Headless mode, Security model.

Elixir / Phoenix — context-first agent sessions

Beam projects reward explicit module names and Mix task discipline. Akmon does not run mix for you unless you approve shell tool calls—so naming conventions in AKMON.md matter.

Prepare AKMON.md

Include:

• Umbrella or single app layout (apps/ vs lib/).
• Contexts that own domain logic (e.g. MyApp.Accounts).
• Preferred checks: mix test, mix format, optional mix dialyzer.

Feature slice — LiveView or controller

akmon --plan --task "Plan a settings page restricted to admin users; list schemas, contexts, and tests to add"

Review .akmon/plans/ then:

akmon --yes --task "Implement the admin settings page per plan; add ExUnit tests for context functions"
mix test

Why plan mode helps

Phoenix moves through router → controller/live → context → schema. A plan file forces the agent to state that order before editing, which reduces half-written plugs or misnamed assigns.

Multi-agent note

You can run a cheap local model for --plan and a stronger cloud model for --yes on the same repo (Multi-agent & automation).

See Other languages for Elixir mentions in the generic profile path.

Example: Next.js + TypeScript

App Router stack with Drizzle, Server Actions, and Shadcn UI.

Setup

npx create-next-app@latest my-app --typescript --app --tailwind --eslint
cd my-app
npx shadcn@latest init

Plan

akmon --plan --task "task management app: auth, Drizzle + Postgres,
CRUD tasks with filters, Server Components + Server Actions,
Shadcn components, middleware protection"

Implement

akmon --yes --task "implement per plan; prefer RSC, use client components only where needed"

Follow-ups

add Playwright E2E for login + task flows

add drag-and-drop ordering with optimistic UI

Example: Refactoring an existing project

Prepare

cd existing-project
akmon init

Edit AKMON.md so conventions match your team before large refactors.

Patterns

Extract service layer

handlers still contain DB + business rules.
move rules to src/services and persistence to src/repositories

Harden error handling

replace unwrap/expect with proper error types and propagation

Add tests

add tests for src/auth — happy paths, invalid input, mocked I/O

Performance

profile hot paths; propose top 3 bottlenecks with fixes

Security audit

review API handlers: validation, authz gaps, sensitive data in logs

Akmon shows diffs before writes — review each change.

Example: Analyzing a codebase

Bootstrap context

cd unfamiliar-project
akmon init
akmon chat

Questions that work well

high-level architecture and main data flows

trace the auth path from HTTP request to response

list the riskiest modules if they were wrong

where is configuration loaded and how does it propagate?

find external HTTP calls missing timeouts

generate a Mermaid diagram of major modules

which tests should I run locally before contributing?

Use /plan for read-only reconnaissance on sensitive trees.

Semantic search

Semantic search lets Akmon find relevant code by meaning, not only exact keyword matches.

When to use it

Use semantic search for questions like:

• "where do we validate JWTs?",
• "what code handles retry/backoff?",
• "where is this business rule enforced?"

It is especially useful when symbols are named inconsistently across a large codebase.

Enabling semantic search

Run Akmon with indexing enabled:

akmon chat --index

On first run, the index build may take time depending on repository size.

Practical workflow

1. ask a high-level question,
2. review candidate files from semantic results,
3. use exact text search/read tools to verify before editing.

Semantic search should guide exploration, not replace source validation.

Cost and context implications

Semantic search can reduce wasted context by narrowing file reads to likely matches instead of broad brute-force scans.

Best practice:

• use semantic search for discovery,
• follow with targeted file reads and scoped edits.

Common mistakes and troubleshooting

• Mistake: treating semantic results as ground truth.
  • Fix: always confirm by reading source files.
• Mistake: expecting semantic indexing in slim builds.
  • Fix: verify your build/runtime mode and --index usage.
• Mistake: indexing generated/vendor directories.
  • Fix: ensure ignore files exclude noisy paths.

See also CLI reference and Capabilities.

Git integration

Akmon uses git context to improve planning and verification, and can perform git operations under policy controls.

What git-aware workflows unlock

• better change understanding (diff, log, status),
• safer review loops (small commits per step),
• easier rollback when automation goes wrong.

Operation classes

Auto-commit strategy

akmon --auto-commit --task "Fix clippy warnings file by file and verify after each change"

When used correctly, this creates small auditable commits that are easier to review and revert.

Prompt patterns that work well

Summarize git diff HEAD~1 in terms of behavior changes and test risk.

Draft a Conventional Commit message for currently staged changes.

Compare this branch to main and list missing tests.

Recommended safety flow

1. ask for analysis (status, diff),
2. apply focused edits,
3. run verification commands,
4. commit only after green checks.

Common mistakes and troubleshooting

• Mistake: one huge commit for many unrelated edits.
  • Fix: split by concern and verify each.
• Mistake: running destructive git commands without review.
  • Fix: keep interactive approval on for mutating commands.
• Mistake: trusting commit message generation without diff review.
  • Fix: always inspect final staged diff before commit.

MCP integration guide

MCP (Model Context Protocol) lets Akmon call external tools on demand: databases, issue trackers, internal APIs, docs systems, and more.

What MCP gives you

Without MCP, developers often paste large external context (schema dumps, issue text, docs) directly into prompts. That is expensive and fragile. MCP changes this model: the agent requests only the data it needs, when it needs it.

Benefits:

• keeps large datasets out of the core prompt context,
• improves context-window efficiency,
• reduces manual copy/paste operations,
• allows repeatable integrations across projects.

Setting up MCP servers

Example configuration in ~/.akmon/config.toml:

[[mcp_servers]]
name = "postgres"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/myapp"]

[[mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/documents"]

Then inspect:

akmon config mcp list
akmon config mcp test postgres
akmon config mcp test github

Real workflow: database-driven development

Scenario: you need SQLAlchemy models from a live schema and do not want to paste DDL.

akmon --model claude-haiku-4-5-20251001

Prompt:

Use available MCP tools to inspect the PostgreSQL schema, then generate SQLAlchemy models and CRUD routes that match current tables and relationships.

Expected behavior:

1. agent discovers MCP tools for postgres,
2. queries schema metadata via MCP tool calls,
3. writes model files from real schema,
4. verifies via project test/lint commands.

Real workflow: GitHub issue execution

Prompt:

Use GitHub MCP to read issue #47, implement the requested change, and create a commit message referencing the issue number.

Expected behavior:

• reads issue content directly from GitHub,
• finds local files to change,
• produces implementation + verification commands,
• prepares commit summary linked to issue context.

Real workflow: external filesystem context

Prompt:

Read ~/documents/api-spec.md via filesystem MCP and update this repository's API handlers to match it.

This is useful when specs, contracts, or governance docs live outside the repository root.

Building a custom MCP server (minimal Python example)

#!/usr/bin/env python3
import json
import sys

TOOLS = [{"name": "hello_company", "description": "Returns internal greeting"}]

for line in sys.stdin:
    req = json.loads(line)
    method = req.get("method")
    rid = req.get("id")
    if method == "tools/list":
        print(json.dumps({"id": rid, "result": {"tools": TOOLS}}), flush=True)
    elif method == "tools/call":
        name = req.get("params", {}).get("name")
        if name == "hello_company":
            print(json.dumps({"id": rid, "result": {"content": "hello from internal system"}}), flush=True)
        else:
            print(json.dumps({"id": rid, "error": {"message": "unknown tool"}}), flush=True)

Wire this script as an MCP server command in config.

Safety and policy model

MCP is not a bypass:

• calls still pass through Akmon policy checks,
• potentially destructive actions can still require confirmation,
• audit logs still record actions and outcomes.

Treat MCP servers like production dependencies: least privilege, scoped credentials, and explicit ownership.

Common mistakes and troubleshooting

• Server starts locally but mcp test fails: check command path and env vars.
• Tool missing in session: verify server is enabled and reachable from runtime shell.
• Slow responses: reduce response size in MCP server output; return focused payloads.
• Risky action exposure: split read-only and write-capable tools into separate servers/credentials.

Audit log

Akmon can emit per-session JSONL audit logs for traceability, debugging, and compliance-oriented workflows.

Why this matters

For AI-assisted development, "it changed some files" is not enough. Teams need to know:

• what the model requested,
• what the policy allowed or denied,
• what commands/files were executed,
• when and why a session stopped.

Audit logs provide this evidence trail.

Log location

Typical path:

.akmon/audit/<session-id>.jsonl

The session id is shown in UI/session output and links runtime behavior to log artifacts.

Typical event categories

• policy decisions (allow, deny, prompted),
• tool lifecycle (requested/executed/completed/failed),
• usage and cost-related summaries,
• session lifecycle transitions (start/done/error).

Example lines:

{"timestamp":"2026-04-06T14:23:11Z","event_kind":"policy_evaluation","permission":"write_file","path":"src/main.rs","verdict":"allow","reason":"user confirmed"}
{"timestamp":"2026-04-06T14:23:15Z","event_kind":"tool_call","tool":"shell","args":{"command":"cargo check"},"result":"ok"}

Useful queries

# show only denied actions
jq 'select(.verdict? == "deny")' .akmon/audit/*.jsonl

# list all file-write decisions
jq 'select(.permission? == "write_file")' .akmon/audit/*.jsonl

Retention and operations

• treat audit logs as operational artifacts,
• rotate or archive old logs,
• avoid committing logs to git unless policy requires it.

Example retention sweep:

find .akmon/audit -type f -mtime +30 -delete

Common mistakes and troubleshooting

• Missing logs: verify audit logging is enabled in your workflow/config.
• Unparsable lines: use line-by-line JSON parser (jq -c) and detect malformed rows early.
• Secrets concern: logs should not contain API keys; if they appear, rotate keys and report immediately.

See also security model and cost guide.

Security model

Akmon treats side-effect control as a core system, not a UI option.

Threat model in plain terms

The main risk is not "model output text." The risk is model-triggered side effects:

• writing files,
• running shell commands,
• accessing network resources,
• mutating git state.

Akmon addresses this with sandboxing, typed permissions, and audit logs.

Sandbox boundaries

File operations are constrained to project boundaries. Path traversal attempts are blocked. This prevents prompt-driven writes to unrelated filesystem locations in normal operation.

Permission classes

Diff-first approvals

For file changes, Akmon can present unified diffs before final approval. This gives human review at the moment side effects happen, not only at the end.

Network and SSRF posture

web_fetch applies protections against common private-address and metadata endpoint abuse patterns. This reduces risk from prompt injection that tries to exfiltrate internal data.

Secrets handling

Operational guidance:

• keep keys in environment or secured config paths,
• never paste production credentials into prompts,
• rotate credentials immediately if leakage is suspected.

What --yes is and is not

--yes is a productivity flag, not a blanket "do anything" bypass. It primarily streamlines read-oriented operations; mutating actions remain policy-gated.

Common mistakes and troubleshooting

• Mistake: enabling broad shell access in unattended workflows.
  • Fix: restrict with precise allow patterns.
• Mistake: assuming audit logs replace code review.
  • Fix: use logs plus normal review/CI controls.
• Mistake: storing sensitive logs in version control.
  • Fix: keep .akmon/ artifacts out of source control unless required.

Cost guide

Akmon is explicit about token usage and estimated spend so you can manage AI work as an engineering budget, not a surprise invoice.

What actually drives costs

For coding agents, the largest cost driver is usually cumulative input tokens, not output tokens. Each model call resends core context plus recent conversation history.

Real session example:

• 35 API calls
• 672k input tokens
• 35k output tokens
• 258k cache-read tokens
• total around $0.68

Using Haiku rates:

• input: 672000 * $0.80 / 1M = $0.5376
• output: 35000 * $4.00 / 1M = $0.1400
• cache reads: 258000 * $0.08 / 1M = $0.0206

Prompt caching and why it matters

Cached prompt reads are much cheaper than fresh prompt tokens. Akmon surfaces cache usage in the footer and session summary so you can see when repeated context is becoming efficient.

Interpretation:

• high cache read ratio often means repeated shared context is being billed at discount rates,
• low cache ratio with high input often indicates noisy/volatile context.

Cost by task type

Model selection strategy

• Haiku: default for most implementation work.
• Sonnet: architecture and hard reasoning spikes.
• GPT-4o-mini: strong budget option if OpenAI is preferred.
• Ollama local models: free token cost, but lower capability and potentially higher latency.

Practical cost controls

Use multiple levers together:

• --max-budget-usd for hard stop,
• plan/spec workflow to avoid repeated exploratory context,
• smaller focused tasks,
• context hygiene (/clear when a session gets noisy),
• use /context and /cost during long runs.

Common mistakes and troubleshooting

• Mistake: using premium models for trivial edits.
• Mistake: allowing sessions to drift into repeated read loops.
• Mistake: ignoring cache/read metrics and only watching final cost.
• Fix: split work by phase and use cheaper models for discovery.

Ollama (local)

Free, offline-capable inference on your machine. No API key required.

Setup

Install Ollama, then:

ollama pull qwen2.5-coder:7b
# or: llama3.2, deepseek-coder-v2, etc.

Akmon

akmon chat
akmon chat --model qwen2.5-coder:7b

Override base URL if needed (see Environment variables for AKMON_OLLAMA_URL).

When to use

• Privacy-sensitive code
• No cloud spend
• Air-gapped or flaky networks

See also Provider setup.

Anthropic

Claude models via the Anthropic API — strong default for quality on code tasks.

Auth

export ANTHROPIC_API_KEY=sk-ant-...

Or anthropic_key in ~/.akmon/config.toml (prefer akmon config key set).

Examples

akmon chat --model claude-haiku-4-5-20251001
akmon chat --model claude-sonnet-4-6
akmon chat --model claude-opus-4-6

Model ids depend on what Anthropic exposes; check their docs for current strings.

Notes

• Prompt caching can reduce cost; Akmon surfaces cache read tokens in the TUI. See Cost transparency.

More: Provider setup.

OpenRouter

One API key for many hosted models. Model ids use a provider/model form.

Auth

export OPENROUTER_API_KEY=sk-or-...

Examples

akmon chat --model anthropic/claude-haiku-4-5
akmon chat --model meta-llama/llama-3.3-70b-instruct
akmon chat --model deepseek/deepseek-chat

Notes

• Pricing and rate limits vary per underlying model.
• Akmon’s cost estimate is heuristic when pricing tables do not list every id.

More: Provider setup.

OpenAI

GPT-family models via the OpenAI API.

Auth

export OPENAI_API_KEY=sk-...

Examples

akmon chat --model gpt-4o
akmon chat --model gpt-4o-mini

Use the exact deployment names your account supports.

More: Provider setup. For Azure, see Azure OpenAI.

Groq

Very fast inference for supported open models.

Auth

export GROQ_API_KEY=gsk_...

Examples

akmon chat --model llama-3.3-70b-versatile
akmon chat --model llama-3.1-8b-instant

See Groq’s model list for current ids.

More: Provider setup.

Azure OpenAI

Enterprise-hosted OpenAI-compatible deployments.

Flags / env

akmon chat \
  --azure-endpoint https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT \
  --azure-key YOUR_KEY \
  --model gpt-4o

Environment variable names may map to AZURE_OPENAI_*; see Environment variables.

Notes

• --model should match your deployment name.
• azure_api_version defaults are CLI-configurable.

More: Provider setup.

Amazon Bedrock

Run Claude and other models inside AWS.

Auth

Typical environment:

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1

Use IAM roles on EC2/EKS where possible instead of long-lived keys.

CLI

akmon chat --bedrock \
  --model anthropic.claude-haiku-4-5-v1:0

Supported model ids change with AWS; consult Bedrock documentation for the latest inventory.

More: Provider setup.

Custom OpenAI-compatible endpoints

Any server that speaks the OpenAI Chat Completions (or compatible) HTTP API — for example LM Studio, vLLM, LiteLLM, Together, Mistral, or a corporate gateway.

CLI

akmon chat \
  --openai-compatible-url http://localhost:1234/v1 \
  --openai-compatible-key optional-if-your-proxy-needs-it \
  --model your-local-model-name

Tips

• URL usually ends with /v1 for OpenAI-style routers.
• Model string must match what the server exposes as model.
• TLS and auth are your responsibility (reverse proxy, VPN, etc.).

More: Provider setup.

Capabilities reference

This page is a practical map of what Akmon can do and how to choose the right mode.

Runtime and packaging

Operating modes

Model/provider support

Akmon supports local and cloud providers, including:

• Ollama (offline/local),
• Anthropic,
• OpenAI-compatible providers,
• OpenRouter, Groq, Azure, Bedrock.

Model selection is per-task, enabling cost/capability optimization.

Core tooling capabilities

• file ops (read/write/edit/patch),
• search (text and optional semantic),
• git context and git actions,
• shell commands (policy constrained),
• network fetch with protections,
• MCP integrations for external systems.

Policy and safety capabilities

• permission-gated side effects,
• write diff confirmation flows,
• sandboxed filesystem boundaries,
• auditable tool + policy events.

Context and memory capabilities

• AKMON.md project steering,
• .akmon/specs persistent plan artifacts,
• session continuation (-c) with resumable context,
• todo and memory primitives for multi-turn continuity.

Cost and observability capabilities

• token and cache visibility in UI,
• cost estimates and run summaries,
• JSONL audit trail for runtime evidence.

Automation capabilities

• headless runs with budget caps,
• structured JSON run output,
• script-friendly command model for batch operations.

Known non-goals

• no hosted SaaS runtime (you run it),
• no mandatory IDE dependency,
• no guarantee that third-party model APIs are available.

Next steps: tutorials overview, headless mode, security model.

CLI Reference

Synopsis

akmon [FLAGS] [SUBCOMMAND]

Flags vary by release — use akmon --help for the authoritative list.

Frequently used flags

Provider flags

Examples:

--anthropic-key
--openrouter-key
--openai-key
--groq-key
--azure-endpoint / --azure-key / --azure-api-version
--bedrock
--aws-region
--openai-compatible-url / --openai-compatible-key

Environment variables usually mirror these; see Environment variables.

Subcommands (typical)

akmon chat
akmon --plan --task "describe module boundaries"
akmon --yes --output json --task "list TODOs" | jq .
akmon import --dry-run
akmon export --all

Subcommand details: akmon <cmd> --help.

Slash Commands

In akmon chat, type / then a command name. Tab may complete available commands.

Session & navigation

Project memory

Models

Planning & specs

Insight

Exact sets may expand — /help inside the app is source of truth.

Configuration reference

This page describes common ~/.akmon/config.toml keys. Exact schemas may grow between releases; use akmon config show for your version.

[model]

Prefer environment variables or akmon config key for secrets so they are not committed.

[architect] / planner

[[model_estimates]]

Optional rows for context-window % and rough USD cost from usage. Each row:

In the TUI, /config (or Ctrl+S) → Estimates edits the row for the active model and writes ~/.akmon/config.toml.

Cost display is not a billing statement. Rate limits are not modeled in-app; set expectations with note or your provider’s dashboard.

See Getting started → Configuration.

MCP servers

Configured as tables under mcp / [[mcp.servers]] (see MCP):

[[mcp.servers]]
name = "example"
url = "https://example.com/mcp"
enabled = true

Paths

Akmon resolves project root (git root), AKMON.md, .akmon/plans/, .akmon/audit/, and optional index paths relative to the project.

CLI

akmon config show    # masked effective config
akmon config path    # config file location
akmon config edit    # open in editor
akmon config reset   # reset options (see help)

Full flag and subcommand matrix: CLI reference.

Tools reference

Akmon’s agent invokes tools the model chooses from a fixed registry. Availability depends on mode (for example plan mode registers read-only tools) and CLI flags (--web-fetch, --index, --shell-allow, …).

Categories

Read & navigate

• read_file — read a file inside the sandbox.
• list_directory — list directory entries.
• search — ripgrep-style content search.

Edit

• write_file — create/overwrite (with confirmation and diff preview).
• edit / patch-style tools — apply targeted edits (with confirmation where configured).

Git

• git — status, diff, log, add, commit, etc. (see Git integration).

Network

• web_fetch — HTTPS fetch with SSRF protections (optional via flag).

Semantic

• semantic_search — embedding search when --index and full build (see Semantic search).

MCP

Dynamic tools from configured MCP servers (MCP).

Permissions

The security model and policy engine decide auto-approval vs confirmation. Writes and dangerous operations require explicit approval unless your mode says otherwise.

Schema

Each tool exposes a JSON Schema for arguments; the model must call with valid JSON. Errors and outputs are fed back to the model and logged to the audit log.

Environment Variables

Secrets are often better as env vars or akmon config key than literals in config.toml.

Provider keys

ANTHROPIC_API_KEY
OPENROUTER_API_KEY
OPENAI_API_KEY
GROQ_API_KEY
AZURE_OPENAI_ENDPOINT      # naming may vary; check CLI help
AZURE_OPENAI_API_KEY
AWS_ACCESS_KEY_ID          # Bedrock
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN          # optional
AWS_DEFAULT_REGION

Runtime behavior

AKMON_OLLAMA_URL           # default http://localhost:11434
EDITOR                     # external edits (/edit-plan, /update-context)
NO_COLOR                   # disable ANSI styling

Detection order (conceptual)

Rough priority when multiple backends could apply:

1. Explicit flags (--bedrock, Azure endpoint, OpenAI-compat URL, …)
2. Model id hints + keys (e.g. OpenRouter ids containing /)
3. Vendor-specific env keys
4. Local Ollama fallback

Use akmon config show (masked) to see what your install resolved.

Wizard vs env vs config.toml

• akmon config (no subcommand) interactively writes ~/.akmon/config.toml.
• The same settings usually have environment variable equivalents listed in the sections above (handy for CI, containers, or secret managers).
• Advanced fields (Architect defaults, [display], MCP entries) are often easiest to edit in TOML or via akmon config mcp …; see Configuration and akmon config --help.

Development Setup

Prerequisites

• Rust matching rust-version in the repo Cargo.toml
• Git

Clone

git clone https://github.com/radotsvetkov/akmon
cd akmon

Build

# Slim / faster — no default feature bundles
cargo build --release --no-default-features

# Full — semantic indexing and related deps
cargo build --release

Test & lint (maintainer expectations)

RUSTFLAGS='-D warnings' cargo test --workspace
cargo clippy --workspace -- -D warnings

Crate map

Dogfood

cargo build --release
./target/release/akmon chat

Pull requests

• Clear description + tests where feasible
• No unwrap in library crates
• rustdoc on new public APIs

Akmon is distributed under the Apache License 2.0 (see repository LICENSE).

Architecture guide for contributors

This document explains how Akmon is organized internally and how the core agent loop works.

Crate structure

akmon/
├── crates/
│   ├── akmon-cli/      # binary entry point, args, command routing
│   ├── akmon-core/     # policies, sandbox, shared types, security primitives
│   ├── akmon-config/   # config loading and provider resolution inputs
│   ├── akmon-models/   # provider adapters and stream normalization
│   ├── akmon-tools/    # tool implementations
│   ├── akmon-query/    # agent loop, context assembly, session lifecycle
│   ├── akmon-tui/      # ratatui UI and runtime bridge
│   └── akmon-index/    # optional semantic index

The agent loop (akmon-query/src/session.rs)

At a high level:

1. build prompt/context bundle,
2. call provider stream,
3. process deltas and stop reason,
4. execute tool calls when requested,
5. append tool results to context,
6. continue loop until model ends with no pending tools.

Stop-reason behavior:

• ToolUse: execute tools, continue loop,
• EndTurn + tool calls: execute then continue,
• EndTurn with no tool calls: complete run,
• MaxTokens: perform continuation strategy where applicable.

This loop is why Akmon behaves like an autonomous worker, not a one-response chatbot.

Context assembly order

Effective ordering in practice:

1. project/system steering (AKMON.md and base system instructions),
2. optional specs/handoff context,
3. language/profile hints,
4. conversation history,
5. dynamic extras (todos/memory blocks).

The order prioritizes stable steering first, then volatile task state later.

Provider abstraction

akmon-models normalizes provider-specific behavior into common stream events and model errors so akmon-query can remain provider-agnostic.

Responsibilities include:

• mapping provider payloads to StreamEvent,
• retry handling where provider-specific (for example rate limits),
• first-token/stream timeout behavior,
• provider display and model-specific heuristics.

Permission system path

Before tool execution:

1. derive concrete permission requirement from tool + args,
2. evaluate policy mode (deny/auto/interative),
3. request user confirmation if needed,
4. execute tool only after allow.

This is enforced centrally in session execution flow, not left to individual tools.

Adding a tool

1. implement Tool trait in akmon-tools,
2. define permission requirements and argument schema,
3. register in tool registry,
4. add unit tests and integration path checks,
5. document in docs/src/reference/tools.md.

Common mistakes and troubleshooting

• Mistake: adding side effects in a read-oriented tool.
• Mistake: bypassing policy path for convenience.
• Mistake: returning unstructured errors that break UX/reporting.
• Fix: keep tool outputs structured and route all side effects through permission-checked paths.

Adding a provider

Providers live in akmon-models. Each backend implements the LlmProvider trait (streaming completions, auth, and provider-specific request shaping).

Steps (overview)

1. Backend module — add a submodule under crates/akmon-models/src/ for the API (HTTP, signing, streaming parse).
2. Implement LlmProvider — map Akmon’s generic message/tool format to the vendor API; handle token usage and errors.
3. Wire config — extend akmon-config / CLI parsing for keys, base URLs, and model id conventions.
4. Detection — update provider auto-detection order (env vars, flags) in CLI/config.
5. Tests — unit-test request JSON and response parsing with fixtures; avoid live API calls in CI.

Conventions

• No .unwrap() in library code; use typed errors (thiserror).
• Never log secrets; use existing Secret types from akmon-core where applicable.
• Document new flags and env vars in user docs (docs/src/providers/, CLI).

See also

• Architecture — crate graph and LlmProvider.
• Development setup — build and test commands.

Changelog

User-facing changes are tracked in the repository’s CHANGELOG.md at the root of the Akmon project.

• Format: Keep a Changelog
• Versions: Semantic Versioning

View online

Open the file on GitHub:

https://github.com/radotsvetkov/akmon/blob/main/CHANGELOG.md

Releases

Tagged releases and binaries are published from the same repo:

https://github.com/radotsvetkov/akmon/releases

When contributing, add a short note under the appropriate ## [x.y.z] section in CHANGELOG.md with your PR.

Security Policy

The same reporting rules and scope are maintained in the repository root as SECURITY.md for GitHub’s security features.

Reporting vulnerabilities

Do not open public issues for undisclosed security problems.

Contact the maintainer privately (see the GitHub profile / repository security instructions). Include:

• Description and impact
• Reproduction steps
• Affected versions / commits if known
• Optional patch ideas

Target initial response: 48 hours (best effort).

Scope

In scope

• Sandbox bypass or path traversal outside the repository root
• SSRF bypasses in web_fetch
• Secret leakage via logs, errors, or persistence
• Permission / policy bypass leading to silent destructive actions

Out of scope

• Physical access scenarios
• Social engineering
• Issues solely inside third-party dependencies (report upstream)

Design reference

Read Security model for how Akmon is intended to behave at runtime.

License

Akmon is licensed under the Apache License, Version 2.0.

The full text is in the repository root as LICENSE.

Why Apache 2.0 for an AI agent tool?

Apache 2.0 is widely used for infrastructure and developer tooling. For projects like Akmon—local-first coding agents, automation glue, and integrations with other tools—it offers:

• Clear redistribution terms when you ship Akmon inside containers, internal CLIs, or custom distributions.
• Explicit patent grant language, which matters when you combine agent runtimes with proprietary stacks or enterprise policies.
• Compatibility with many corporate open-source approval processes compared to more ambiguous or custom terms.

If you embed Akmon or ship derivative work, keep the LICENSE file and any required notices with your distribution, and follow the Apache 2.0 attribution requirements for modified files.