Introduction

Akmon is the review-aware AI coding agent for regulated engineering. It is built for teams where "the model suggested it" is not enough evidence to merge, release, or certify software changes. Every session is captured as a tamper-evident, content-addressed artifact that can be replayed, compared, and verified later.

Akmon is intentionally not a "best autocomplete UX" product. It is a terminal-first control plane for AI-assisted code change work where traceability, deterministic evidence, and explicit operator control are non-negotiable. The core question is simple: when an auditor, reviewer, or incident responder asks what happened, can you prove it?

This page explains the problem Akmon is designed to solve, the design choices behind it, what ships in v2.0.0, and where Akmon is intentionally not trying to compete.

The problem Akmon was built to solve

AI coding agents can now produce meaningful code changes, but many environments still cannot rely on them for critical work. The blocker is usually not raw model capability. The blocker is evidence quality.

Teams repeatedly run into the same questions:

• What exactly did the agent read?
• What tools did it call?
• What side effects happened on disk or in shell?
• Which policy decision allowed each side effect?
• Can we replay the run and validate that the artifact is still intact?

In many tools, those answers are partial or ephemeral. You get a useful session in the moment, but weak forensic value later. That gap is acceptable for low-risk prototyping. It is a hard stop for regulated release workflows.

Provider lock-in is the second recurring failure mode. Model quality, latency, legal terms, and cost change over time. If your coding workflow depends on one provider's roadmap, your engineering process inherits that business risk. Regulated teams and enterprise teams often need optionality: local models for sensitive code paths, hosted models for throughput, and explicit controls over where prompts go.

Operational portability is the third issue. Real engineering happens in mixed environments:

• local laptops,
• remote SSH sessions,
• CI runners,
• hardened enterprise hosts,
• restricted network segments.

If the agent requires a specific IDE plugin stack or heavyweight runtime chain, adoption collapses outside a narrow desktop workflow. Akmon is built for those constraints first.

The design decisions (and why)

Single binary

Akmon ships as a standalone Rust binary. That has practical effects beyond install convenience.

• Runtime state is explicit and portable.
• Environment drift is reduced relative to dynamic plugin/runtime stacks.
• CI and remote-host deployment stay simple.

If two machines run the same Akmon version, behavior is easier to reason about and support. Troubleshooting tends to focus on policy, provider config, repository state, or model behavior rather than host runtime mismatch.

Bring your own key / bring your own model

Akmon supports Anthropic, OpenAI, OpenRouter, Groq, Azure OpenAI, Bedrock, OpenAI-compatible endpoints, and Ollama. Model selection remains an operator decision.

That matters for:

• commercial leverage,
• legal and data-boundary control,
• outage resilience,
• per-task cost/performance tuning.

The objective is not to force one "best model." The objective is to keep model strategy decoupled from tooling adoption.

Typed permission boundaries

Akmon treats tool operations as explicit capabilities, not implicit side effects. Reads, writes, shell execution, and network actions are mediated through policy and approval flow.

This creates a clear boundary:

• the model can request an action,
• the runtime can enforce policy,
• the operator can review and approve or deny.

That boundary is critical in environments where side effects must be reviewable and explainable.

Session evidence as a first-class output

Most tools treat logs as support artifacts. Akmon treats the session artifact as a product output.

A useful AI run is not just "did it produce code." A useful AI run is "can we verify what happened and carry that evidence through review, CI, and audit."

Context discipline

Akmon encourages explicit context shaping rather than perpetual thread growth. Teams typically get better outcomes when they separate work into:

1. exploration,
2. planning/specification,
3. implementation and verification.

This reduces context drift and makes outcomes easier to reproduce.

The session evidence model in v2.0.0

v2.0.0 centers Akmon around a deterministic session evidence workflow. The system records each run as a content-addressed event journal with cryptographic chain integrity. That gives reviewers a concrete object to inspect instead of reconstructing behavior from partial logs.

At a high level:

• Events are linked in order and integrity-checked.
• Session contents can be replayed deterministically against recorded providers/tools.
• Two sessions can be compared structurally and at field level.
• Evidence can be exported into AGEF bundles for portability.

Akmon v2.0.0 implements AGEF v0.1.1 as a practical reference implementation for portable AI-agent session evidence. The goal is operational interoperability and verifiability, not vendor-specific lock-in.

Command surface in v2.0.0

v2.0.0 command workflow centers around:

• chat / --task for execution entry points,
• doctor for provider diagnostics,
• inspect and diff for session analysis,
• verify, audit, and evidence for integrity and evidence validation,
• replay for deterministic comparison,
• bundle export / bundle import and redact for portable and sanitized handoff.

These commands are meant to compose. A common pattern is:

1. run a task,
2. inspect/diff output,
3. verify/audit integrity,
4. export/redact evidence for downstream review.

Who Akmon is for

Akmon targets teams that must prove what AI did, not just benefit from what AI suggested.

Aerospace and avionics teams

For organizations working under DO-178C-style qualification and evidence pressure, session traceability and deterministic replay reduce ambiguity during review.

Medical device software teams

For IEC 62304-oriented development, controlled side effects and audit-ready artifacts support stronger change documentation and risk controls.

Automotive software teams

For ISO 26262-influenced workflows, reproducible agent behavior and explicit evidence chains improve confidence in AI-assisted modifications.

Finance and enterprise controls teams

For SOC 2 or similar control environments, the session artifact model helps demonstrate governance over AI-driven code changes.

Defense and high-assurance environments

For CMMC-style and restricted-network contexts, single-binary deployment, policy boundaries, and provider flexibility are practical adoption requirements.

Platform and SRE teams

For teams running large automation surfaces in CI, structured outputs and verifiable artifacts make autonomous tasks easier to gate and monitor.

What Akmon is intentionally not

Akmon is opinionated about scope. That includes clear non-goals.

• It is not trying to replace IDE-native completion workflows.
• It is not optimized for maximum "chat polish" over evidentiary rigor.
• It is not tied to a single model provider's product strategy.
• It is not built around opaque, non-replayable agent behavior.

Those tradeoffs are deliberate. Akmon prioritizes reviewability, operational control, and portability over broad UX coverage.

Practical usage guidance

Use model tiers intentionally

Use lower-cost models for exploration and mechanical edits. Use stronger models for architecture or multi-file reasoning. This keeps cost predictable without forcing one model for every task.

Keep project context explicit

Maintain AKMON.md with constraints, architecture notes, and decision boundaries. High-quality local context usually improves output quality more than longer ad-hoc prompts.

Treat evidence generation as part of done

In regulated workflows, task completion includes evidence readiness. A run is not complete until required verification and artifact checks pass.

Gate automation with policy and verification

For headless workflows, use explicit policy, budget limits, and integrity checks so autonomous runs fail closed when constraints are violated.

Adoption notes for regulated teams

Teams adopting Akmon in regulated contexts usually move in phases instead of switching everything at once.

Phase 1: Observe

Start by running scoped tasks with full session capture enabled. Focus on understanding evidence quality and policy fit before broad automation.

Phase 2: Constrain

Introduce tighter policy defaults and approval rules for writes, shell, and network operations. Treat denied operations as useful feedback about control boundaries, not as friction to bypass.

Phase 3: Verify

Standardize post-run verification steps in CI and review checklists. Require session integrity checks for categories of changes where auditability is mandatory.

Phase 4: Operationalize

Package repeatable workflows for common engineering tasks and gate them with policy and evidence requirements. The goal is consistent, reviewable operation rather than maximal autonomy.

This phased approach keeps rollout practical:

• engineers get immediate utility,
• governance teams get deterministic evidence,
• reliability standards are raised without blocking delivery.

Where to go next

• Install and first run: Getting Started
• Headless automation: Headless mode
• Interactive usage: Interactive mode
• Policy controls: Policy profiles
• Core terms: Glossary
• Reviewer handoff: Regulated reviewer flow
• Session comparison: Session diff reference
• 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 →

Glossary

Documented for Akmon 2.0.0.

Who this is for

Readers who want consistent terminology across Akmon tutorials, references, and review workflows.

What you will have at the end

• Canonical meanings for Akmon terms used in docs and CI policy discussions.

Prerequisites

• None.

Terms

• Session: one Akmon run context identified by a UUID and recorded as linked events.
• Artifact: output file produced by a run (for example evidence JSON, audit JSONL, or .akmon bundle).
• Evidence: structured JSON artifact (evidence.v1) summarizing replay metadata, policy/tool outcomes, and verification context.
• Verify: integrity check command (akmon verify) that validates hash chain, object closure, and session invariants.
• Replay: deterministic re-execution and comparison of a recorded session (akmon replay) using replay modes.
• Policy: allow/deny control layer over tool/file/network/shell actions, including profile and pack merging.
• Capability: an action class available to the runtime and model through registered tools and commands.
• Bundle: portable .akmon archive containing manifest, event stream, and referenced objects for transport/import.
• Audit log: JSONL chain capturing auditable events for a session (.akmon/audit/<session-id>.jsonl).
• Policy profile: built-in baseline policy (dev, staging, prod) selectable by CLI/config.
• Policy pack: operator-maintained TOML/JSON policy layer merged on top of profile defaults.
• Sentinel: replacement object marker used by akmon redact to remove sensitive object bytes while preserving structure.

Verification

Use this glossary as the canonical reference when terms differ between teams or review templates.

Troubleshooting

• If a term is missing, check reference pages first and then update this glossary in the same PR as the feature/docs change.

Regulated Reviewer Flow

Documented for Akmon 2.0.0.

Who this is for

Reviewers, tech leads, and compliance engineers validating AI-assisted code-change sessions.

What you will have at the end

• A single repeatable checklist from run output to verification-ready handoff.

Prerequisites

1. A completed Akmon run with session ID.
2. Access to repository artifacts (.akmon/audit, .akmon/evidence).

Steps

1. Capture the session ID from run output.

SESSION_ID="<session-uuid>"

2. Verify audit chain and evidence artifact linkage.

akmon audit verify ".akmon/audit/${SESSION_ID}.jsonl"
akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"

3. Verify session integrity at journal level.

akmon verify "${SESSION_ID}"

4. Replay for behavioral divergence checks when required.

akmon replay "${SESSION_ID}" --format json | tee replay.json

5. Export portable bundle for external review or archive retention.

akmon bundle export "${SESSION_ID}" --output "${SESSION_ID}.akmon"

6. If sensitive content must be removed, create derivative redacted bundle.

akmon redact "${SESSION_ID}" \
  --output "${SESSION_ID}-sanitized.akmon" \
  --object <object-hash> \
  --reason "compliance redaction"

Verification

A handoff is review-ready when:

• all verification commands exit 0,
• replay report is pass or divergences are explicitly accepted,
• exported bundle is present and, if redacted, passes bundle import --verify-only.

Troubleshooting

• If verify fails, stop release review and inspect violation category before proceeding.
• If replay diverges, treat as change-detection signal and triage expected vs unexpected drift.
• If bundle import verify-only fails, do not distribute the bundle externally.

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.

Tutorial: Local-first developer flow (Ollama)

Documented for Akmon 2.0.0.

Time estimate: 15-20 minutes
Complexity: Beginner

Who this is for

Developers who want a fully local Akmon workflow with verifiable session evidence.

What you will have at the end

• One interactive local session.
• One equivalent headless JSON run.
• Verified audit/evidence artifacts for review.

Prerequisites

1. akmon --version prints 2.0.0 (or your current build).
2. ollama is installed and running.
3. You are inside a git repository.

Steps

1. Pull a local model and verify Akmon.

ollama pull qwen2.5-coder:7b
akmon --version

2. Start interactive mode with a local model and dev policy profile.

cd /path/to/your-repo
akmon --model qwen2.5-coder:7b --policy-profile dev chat

3. Run one controlled implementation request.

add validation to the registration handler and update tests

Expected result: Akmon asks for approvals before write actions.

4. Run an equivalent headless task for machine-readable artifact output.

akmon --model qwen2.5-coder:7b --yes --output json \
  --task "add validation to the registration handler and update tests" \
  | tee run.json

5. Extract the session ID and verify recorded artifacts.

SESSION_ID="$(jq -r '.session_id' run.json)"
akmon audit verify ".akmon/audit/${SESSION_ID}.jsonl"
akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"
akmon verify "${SESSION_ID}"

What gets recorded in evidence

• Session metadata (session/model/provider context).
• Tool execution and reliability metrics.
• Replay metadata and policy/tool registry hashes.
• Paths to audit/evidence artifacts for review handoff.

How a reviewer validates this

1. Confirm akmon verify <session-id> exits 0.
2. Confirm akmon audit verify and akmon evidence verify both succeed.
3. Inspect run.json fields (session_id, status, reliability_metrics, replay_metadata) for expected run characteristics.

Verification

jq '{session_id,status,reliability_metrics,replay_metadata}' run.json

Expected result: JSON object includes non-empty session_id and status.

Troubleshooting

• If Ollama is unavailable, check ollama ps and retry.
• If provider resolution is unexpected, run akmon config explain-provider.
• If first local response is slow, warm with ollama run qwen2.5-coder:7b once before rerunning.

Tutorial: CI headless governance flow

Documented for Akmon 2.0.0.

Time estimate: 20-30 minutes
Complexity: Intermediate

Who this is for

Teams running Akmon non-interactively in CI with explicit budget and reliability guardrails.

What you will have at the end

• A reproducible headless run command.
• Integrity verification gates (audit, evidence, verify).
• SLO and trend checks that can fail CI on policy or reliability regressions.

Prerequisites

1. CI runner has akmon installed.
2. Runner has provider credentials (for example ANTHROPIC_API_KEY) or local model setup.
3. Repository has write access to .akmon/ output paths.

Steps

1. Execute a headless run with JSON output and budget cap.

akmon --yes --output json \
  --max-budget-usd 2.00 \
  --task "run cargo test and summarize failures" \
  | tee run.json

2. Extract session ID and run integrity checks.

SESSION_ID="$(jq -r '.session_id' run.json)"
akmon audit verify ".akmon/audit/${SESSION_ID}.jsonl"
akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"
akmon verify "${SESSION_ID}"

3. Enforce per-run SLO thresholds.

akmon slo verify ".akmon/evidence/${SESSION_ID}.json" \
  --thresholds .github/akmon/slo.toml \
  --strict

4. Enforce trend gate against historical baseline.

akmon slo trend ".akmon/evidence/${SESSION_ID}.json" \
  --baseline-dir .akmon/evidence/history \
  --window 20 \
  --strict

5. Wire the same sequence into CI.

- name: Run Akmon headless
  run: akmon --yes --output json --task "run tests and summarize failures" | tee run.json

- name: Extract session ID
  run: echo "SESSION_ID=$(jq -r '.session_id' run.json)" >> $GITHUB_ENV

- name: Verify audit, evidence, and session integrity
  run: |
    akmon audit verify ".akmon/audit/${SESSION_ID}.jsonl"
    akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"
    akmon verify "${SESSION_ID}"

- name: Enforce SLO and trend guardrails
  run: |
    akmon slo verify ".akmon/evidence/${SESSION_ID}.json" --strict
    akmon slo trend ".akmon/evidence/${SESSION_ID}.json" --baseline-dir .akmon/evidence/history --window 20 --strict

What gets recorded in evidence

• Reliability metrics used by slo verify and slo trend.
• Replay metadata hashes for deterministic validation context.
• Provider resolution and session-level run status.

How a reviewer validates this

1. Confirm all integrity commands exit 0.
2. Confirm SLO/trend gates produce pass/fail outputs matching policy thresholds.
3. Confirm CI artifacts include run.json and evidence files for retained runs.

Verification

jq '{session_id,status,reliability_metrics}' run.json

Expected result: non-empty session_id, explicit status, and reliability metrics object.

Troubleshooting

• If CI fails before Akmon starts, verify provider credentials in runner environment.
• If slo verify fails, inspect threshold file and violations output.
• If policy denies block the run, inspect policy_denials_total in metrics and reconcile with configured profile/packs.
• Failure behavior is intentional: non-zero exits from audit/evidence/verify/slo should fail pipeline gates.

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

Scout dossier to implementation

Use the bounded scout flow to improve implementation context without enabling broad multi-agent orchestration:

# 1) Generate a read-only dossier
akmon scout \
  --task "find provider resolution paths and doctor coverage gaps" \
  --max-files 250 \
  --out .akmon/context/provider-scout.json

# 2) Inspect the dossier
jq '.confidence, .candidate_files[0:5], .constraints' .akmon/context/provider-scout.json

# 3) Run implementation with dossier context injected
akmon \
  --dossier .akmon/context/provider-scout.json \
  --task "implement provider resolution explainability with tests and docs"

Tutorial: Enterprise policy profile rollout

Documented for Akmon 2.0.0.

Time estimate: 30-40 minutes
Complexity: Advanced

Who this is for

Platform/security teams introducing policy governance from developer-friendly defaults to production guardrails.

What you will have at the end

• A staged rollout flow across dev, staging, and prod.
• An org policy pack with deterministic merge behavior.
• Evidence-driven checks showing what denials look like in practice.

Prerequisites

1. Repository contains .akmon/ directory.
2. You can run headless tasks (akmon --task ...).
3. Team agrees on approval and CI gate expectations.

Steps

1. Establish baseline with built-in dev profile.

akmon policy show-effective --profile dev
akmon --policy-profile dev --task "list API modules and summarize auth boundaries"

2. Add an organizational policy pack.

Create .akmon/policy-packs/org.toml:

[tools]
deny = ["shell"]

[network]
deny_domains = ["*"]

Inspect effective result:

akmon policy show-effective --profile dev --policy-pack .akmon/policy-packs/org.toml

3. Roll into staging for CI-like gating.

akmon policy show-effective --profile staging --policy-pack .akmon/policy-packs/org.toml
akmon --policy-profile staging --policy-pack .akmon/policy-packs/org.toml --yes --output json \
  --task "run non-mutating checks and summarize findings" | tee staging-run.json

4. Promote to prod and validate expected denials.

akmon policy show-effective --profile prod --policy-pack .akmon/policy-packs/org.toml
akmon --policy-profile prod --policy-pack .akmon/policy-packs/org.toml \
  --task "run shell command: cargo test"

Expected result: command path involving shell is denied by policy.

5. Confirm allowed read-heavy workflow still succeeds.

akmon --policy-profile prod --policy-pack .akmon/policy-packs/org.toml \
  --task "list auth module files and summarize"

Merge precedence: profile < packs < project-local policy < CLI override

What gets recorded in evidence

• Policy decision counters (allow/deny/prompted).
• Decision samples and replay metadata policy hash.
• Reliability metrics showing denial events in governed runs.

How a reviewer validates this

1. Compare akmon policy show-effective output across profiles.
2. Confirm expected deny behavior appears for prohibited capabilities.
3. Verify governed run artifacts with audit/evidence/verify.

Verification

SESSION_ID="$(jq -r '.session_id' staging-run.json)"
akmon audit verify ".akmon/audit/${SESSION_ID}.jsonl"
akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"
akmon verify "${SESSION_ID}"

Anti-patterns

• Moving directly to prod without staging validation.
• Using ad hoc CLI overrides in CI without documenting governance rationale.
• Interpreting denial-heavy runs as failures without checking policy intent.

Troubleshooting

• If policy file parsing fails, validate TOML syntax and paths.
• If effective view is empty, confirm selected profile/packs are actually passed.

Tutorial: Example projects for regulated teams

Documented for Akmon 2.0.0.

Time estimate: 25-35 minutes
Complexity: Intermediate

Who this is for

Teams validating Akmon in greenfield repositories before production rollout.

What you will have at the end

• One reproducible starter run per stack.
• Session evidence and audit artifacts suitable for reviewer checks.
• A baseline pattern you can adapt to internal policies.

Prerequisites

1. akmon --version works.
2. Provider configuration is already validated (akmon doctor providers).
3. You can create local git repositories.

Steps

1. Run one starter scenario (Rust, Python, or TypeScript).

Rust API starter (illustrative medical-device backend context)

Constraints:

• Data boundary: no external network calls beyond approved dependencies.
• Review requirement: all generated handlers must have tests.

mkdir -p ~/projects/rust-api && cd ~/projects/rust-api
git init
akmon --yes --output json --task "create an Axum REST API skeleton with tests" | tee run.json

Python FastAPI starter (illustrative fintech controls context)

Constraints:

• Approval requirement: write operations must remain explicit (--yes only auto-approves read-only tools).
• CI requirement: pytest must be runnable.

mkdir -p ~/projects/fastapi-service && cd ~/projects/fastapi-service
git init
akmon --yes --output json --task "create FastAPI app with /health endpoint and pytest test" | tee run.json

TypeScript service starter (illustrative defense supplier context)

Constraints:

• Audit need: deterministic artifact capture for external review.
• CI requirement: include at least one basic route test.

mkdir -p ~/projects/node-service && cd ~/projects/node-service
git init
akmon --yes --output json --task "create Node TypeScript service with basic route and test" | tee run.json

2. Verify run artifacts.

SESSION_ID="$(jq -r '.session_id' run.json)"
akmon audit verify ".akmon/audit/${SESSION_ID}.jsonl"
akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"
akmon verify "${SESSION_ID}"

What gets recorded in evidence

• Session identifier, run status, and replay metadata hashes.
• Tool execution metrics and policy decision summary.
• Linked audit path for tamper-evident review.

How a reviewer validates this

1. Confirm the three verification commands exit 0.
2. Confirm run.json contains expected session_id, status, and reliability_metrics.
3. Confirm produced files and tests align with requested starter scope.

Verification

jq '{session_id,status,files_written,reliability_metrics}' run.json

Anti-patterns

• Running starter flows without storing run.json (loses machine-readable evidence context).
• Treating a successful run as policy-compliant without verification commands.
• Sharing artifacts externally before audit/evidence/verify checks pass.

Troubleshooting

• If generation fails on provider setup, run akmon doctor providers.
• If verification fails, ensure SESSION_ID came from the same run.json.

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.

Safety defaults for nested runs

Subagents are intentionally conservative:

• no implicit broad approvals are injected at nested bootstrap,
• nested execution is capped by the parent permission posture,
• when parent policy is interactive, nested runs stay read-oriented unless policy can be satisfied automatically,
• side-effect tools that exceed the parent ceiling are filtered out before nested execution.

Practical guidance:

• use subagents for research/summarization,
• perform high-impact write/shell steps in the main session where approvals are explicit,
• if a nested run reports ceiling restrictions, tighten task scope to read-only discovery.

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

Documented for Akmon 2.0.0.

Who this is for

Engineers installing Akmon on macOS or Linux for local development, CI, or remote shell usage.

What you will have at the end

• A runnable akmon binary on PATH.
• A verified installation (akmon --version).
• A clear fallback path for source builds.

Prerequisites

• Shell access on macOS or Linux.
• curl available.
• Rust 1.88+ only if building from source.

Steps

1. Install from a release binary (recommended).

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 2.0.0

2. If binary install fails, build from source.

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/

3. (Optional) Install from crates.io if available in your workflow.

Option 3 — cargo install

cargo install akmon

Verification

command -v akmon
akmon --version
akmon --help

Expected result: all commands succeed and print usage/version output.

Troubleshooting

• If akmon is not found, add ~/bin to PATH and restart your shell.
• If downloaded file is HTML, verify the release asset name and tag availability.
• For provider failures after install, run akmon doctor providers.

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

Documented for Akmon 2.0.0.

Who this is for

Engineers who want a first successful Akmon run in a local repository using either a local model (Ollama) or hosted provider credentials.

What you will have at the end

• One completed Akmon session in your project.
• A recorded audit log and evidence artifact for that session.
• A baseline understanding of interactive and headless entry points.

Prerequisites

1. akmon --version works.
2. You are inside a git repository.
3. One provider path is ready:
   • Local: ollama running with a pulled model.
   • Hosted: one of ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, or Azure/Bedrock settings.

Steps

1. Choose a model source.

# Local-first example
ollama pull qwen2.5-coder:7b

# Hosted example (pick one)
export ANTHROPIC_API_KEY="YOUR_KEY"

Expected result: provider prerequisites are available before Akmon starts.

2. Start Akmon in interactive mode.

cd /path/to/your-repo
akmon

Expected result: full-screen TUI opens for a new session.

3. Run a read-only exploration prompt.

explain where authentication state is created and validated

Expected result: Akmon reads/searches files and returns an explanation with tool traces in-session.

4. Run one bounded implementation prompt.

add input validation to create_user and explain the tests required

Expected result: Akmon proposes file edits with approval gates before writes.

5. End the session cleanly.

/exit

Expected result: session summary appears and Akmon saves artifacts.

Verification

Check that session evidence exists in the project:

ls -1 .akmon/audit .akmon/evidence

Then verify integrity:

# Replace with your session UUID
akmon verify <session-uuid>

Expected result:

• akmon verify exits 0 for a valid session chain.
• Audit/evidence files are present for reviewer handoff.

Troubleshooting

• If startup fails with provider errors, run akmon doctor providers.
• If model routing is unclear, run akmon config explain-provider.
• If Ollama is slow on first turn, warm model once with ollama run <model>.
• If you need machine-readable output for CI, use headless mode:

akmon --task "run tests and summarize failures" --output json --yes

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.

Troubleshooting flow (akmon doctor providers + akmon config explain-provider)

Routing behavior is unchanged—these commands only explain which resolver branch would win for your current --model, flags, and ~/.akmon/config.toml.

Walkthrough: “Why am I on Ollama instead of OpenAI?”

1. Show the resolution trace (text or JSON):

   akmon config explain-provider
   akmon config explain-provider --json
   

   Read selected_provider, then scan candidates[] in priority_order order. Each row states why a branch was skipped, matched, or would have failed (named prerequisites only—no secrets).

2. Cross-check health and endpoints:

   akmon doctor providers
   akmon --output json doctor providers
   

   The JSON report includes the same provider_resolution block plus reachability and masked key checks.

3. Fix the first issue that applies: missing env vars or flags listed under missing_prerequisites, Azure endpoint/key mismatch, or Ollama not running—then re-run step 1.

Doctor-only checklist

Run:

akmon doctor providers

JSON mode:

akmon --output json doctor providers

Use this flow:

1. Fix all base_url/endpoint sanity failures first.
2. Fix missing key/auth checks for the provider you actually run with.
3. Resolve reachability failures (network, DNS, firewall, service down).
4. Re-run doctor until active provider is healthy.

Common pitfalls flagged by doctor:

• Azure endpoint missing deployment path (/openai/deployments/<name>/chat/completions)
• OpenAI-compatible endpoint set without key
• OpenRouter/OpenAI key missing while model selection implies that provider
• Ollama URL valid but service unreachable (ollama serve not running)

Local reliability troubleshooting (Ollama)

When local runs stall or return empty output:

1. Check server/process state first:
   • ollama ps
2. Warm the model before long tasks:
   • ollama run <model>
3. If the session has drifted to large context:
   • use /clear, then retry
4. If tool-heavy tasks keep stalling:
   • switch to a known tool-capable local model, for example:
   • /model qwen2.5-coder:7b

Akmon now emits consistent loading/status hints in both streaming and buffered paths, and timeout/no-output errors include recovery actions so operators can recover without guesswork.

Configuration

Documented for Akmon 2.0.0.

Who this is for

Engineers configuring Akmon for repeatable local use, CI usage, and policy/evidence-aware operation.

What you will have at the end

• A valid ~/.akmon/config.toml.
• A clear precedence model: CLI flags > environment > config file.
• Verified provider routing and masked config inspection commands.

Prerequisites

1. akmon --version works.
2. You have either local Ollama or hosted provider credentials.
3. You can run commands in a terminal where ~/.akmon/ is writable.

Steps

1. Run the interactive setup wizard (optional, quickest start).

akmon config

Expected result: Akmon writes ~/.akmon/config.toml.

2. Inspect the effective stored config safely.

akmon config show

Expected result: keys are masked in output.

3. Set or update common values with explicit subcommands.

akmon config model set qwen2.5-coder:7b
akmon config ollama-url set http://localhost:11434

4. Verify provider resolution for the current model and environment.

akmon config explain-provider

Expected result: deterministic provider decision trace with candidate reasons.

5. If you manage credentials in file form, use top-level keys from AkmonGlobalConfig.

default_model = "qwen2.5-coder:7b"
ollama_url = "http://localhost:11434"
# anthropic_api_key = "sk-ant-..."
# openrouter_api_key = "sk-or-..."

[architect]
planner_model = "llama3.2"

[policy]
profile = "dev"
packs = [".akmon/policy-packs/team.toml"]

Verification

akmon config path
akmon config show --json
akmon doctor providers

Expected result:

• config path resolves to ~/.akmon/config.toml
• JSON output parses cleanly
• doctor reports either healthy provider checks or actionable failures

Troubleshooting

• akmon config --json without subcommand is invalid by design; use akmon config show --json.
• If TUI scrollback is missing, export with /transcript to .akmon/transcript_export.md.
• If provider selection is unexpected, compare akmon config explain-provider with your env vars.
• Store secrets in environment variables for CI rather than committing config files.

Model context and cost estimates (model_estimates)

model_estimates rows are optional hints for context window and rough USD estimation.

[[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."

See also Environment variables and Configuration reference.

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.

Policy profiles in interactive sessions

You can run interactive sessions with enterprise policy profiles/packs:

akmon chat --policy-profile dev
akmon chat --policy-profile staging --policy-pack .akmon/policy-packs/org.toml

Inspect the final merged configured policy before starting:

akmon policy show-effective --profile staging --policy-pack .akmon/policy-packs/org.toml

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 is for CI and scripted runs.

Basic run

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

Default artifacts:

• audit: .akmon/audit/<session-id>.jsonl
• evidence: .akmon/evidence/<session-id>.json

CI governance flow

# run
akmon --yes --output json --task "run unit tests and summarize failures" | tee run.json

# verify trust artifacts
akmon audit verify .akmon/audit/<session-id>.jsonl
akmon evidence verify .akmon/evidence/<session-id>.json

# enforce SLO policy
akmon slo verify .akmon/evidence/<session-id>.json --strict

# enforce trend regression gate
akmon slo trend .akmon/evidence/<session-id>.json \
  --baseline-dir .akmon/evidence/history \
  --window 20 \
  --strict

JSON report fields

Headless JSON includes:

• lifecycle fields (status, exit_reason, result),
• usage/cost fields,
• additive replay_metadata,
• additive reliability_metrics.

Use exit_reason + command exit code for CI gating.

Exit code guidance

• akmon run: process exits non-zero on runtime/config failures.
• akmon audit verify: 0 valid, 1 invalid/missing.
• akmon evidence verify: 0 valid, 1 invalid/missing.
• akmon slo verify: 0 pass, 1 violation, 2 invalid input/config.
• akmon slo trend: 0 pass, 1 violation, 2 invalid input/config.

Common mistakes

• Running unattended jobs without --max-budget-usd.
• Parsing only old JSON fields and ignoring additive metrics/replay blocks.
• Using broad tasks instead of scoped, verifiable tasks.

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

Documented for Akmon 2.0.0.

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

Scenario

Industry/context (illustrative): defense-adjacent internal API with strict review and evidence expectations.

Constraints

• Data boundary: local/dev database only for example.
• Approval requirement: layered implementation and test coverage.
• CI requirement: reproducible cargo checks.

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

Outcome

Artifacts answer: "What changed, why, and can we verify the session chain?"

• .akmon/audit/<session-id>.jsonl
• .akmon/evidence/<session-id>.json
• Optional headless run.json for CI records

Anti-patterns

• Implementing auth + persistence + routing in a single unreviewed turn.
• Skipping --plan for large multi-module changes.

Example: CLI tool with Python

Documented for Akmon 2.0.0.

Scenario

Industry/context (illustrative): regulated ops tooling where command outputs feed compliance reports.

Constraints

• Data boundary: avoid leaking secrets in CLI output/logs.
• Approval requirement: explicit schema validation for external API fields.
• CI requirement: stable command behavior with tests.

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

Outcome

You get a structured CLI implementation path plus traceable Akmon run artifacts for review.

Anti-patterns

• Treating API JSON as untyped dicts in production-facing commands.
• Merging CLI UX and transport refactors into one unreviewed session.

Python web services — Flask & FastAPI

Documented for Akmon 2.0.0.

Scenario

Industry/context (illustrative): healthcare integration service requiring auditable API modifications.

Constraints

• Approval requirement: auth and validation behavior must follow existing conventions.
• CI requirement: pytest required for each change slice.
• Audit need: evidence artifact retained for API behavior review.

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.

Outcome

This flow provides framework-specific modifications with explicit test and evidence expectations.

Anti-patterns

• Adding authenticated routes without mirroring existing auth dependency patterns.
• Accepting framework drift (mixed app-factory and module-level startup styles) in the same refactor.

Elixir / Phoenix — context-first agent sessions

Documented for Akmon 2.0.0.

Scenario

Industry/context (illustrative): defense supplier internal portal with strict module ownership and review controls.

Constraints

• Approval requirement: context/module boundaries must remain explicit.
• CI requirement: mix test required after implementation.
• Audit need: preserve evidence for each feature-slice run.

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 local model for planning and a hosted model for implementation on the same repository when policy allows.

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

Outcome

The result is a context-aligned Phoenix feature slice with a reviewable plan-to-implementation trace.

Anti-patterns

• Editing router, contexts, and schemas without an explicit plan artifact first.
• Treating Mix checks as optional in regulated delivery workflows.

Example: Next.js + TypeScript

Documented for Akmon 2.0.0.

Scenario

Industry/context (illustrative): fintech internal portal requiring policy-aware change traces.

Constraints

• Approval requirement: keep server/client boundaries explicit.
• CI requirement: lint + test + E2E flow readiness.
• Audit need: headless run record for reviewer replay path.

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

Outcome

You get a planned and implemented Next.js slice with evidence artifacts and reproducible command history.

Anti-patterns

• Defaulting all logic to client components without rationale.
• Shipping feature flows without test prompts in the same review cycle.

Example: Refactoring an existing project

Documented for Akmon 2.0.0.

Scenario

Industry/context (illustrative): medical software backend needs controlled refactoring with explicit reviewer traceability.

Constraints

• Approval requirement: no silent architecture rewrites.
• CI requirement: tests must pass after each scoped change.
• Audit need: maintain session evidence for each refactor batch.

Prepare

cd existing-project
akmon init

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

Akmon workflow 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.

Outcome

You should produce:

• Small, reviewable refactor batches.
• Evidence artifacts per batch run.
• A reviewer-auditable path from prompt to file changes.

Anti-patterns

• Asking for "full project refactor" in one turn.
• Skipping verification/tests between structural changes.

Example: Analyzing a codebase

Documented for Akmon 2.0.0.

Scenario

Industry/context (illustrative): regulated fintech service onboarding a new engineer for read-only architecture review.

Constraints

• Data boundary: no uncontrolled writes during discovery.
• Approval requirement: keep first pass read-oriented.
• Audit need: produce artifacts reviewers can verify.

Akmon workflow

cd unfamiliar-project
akmon init
akmon --plan --task "map architecture, auth path, config flow, and top risk modules"
akmon --yes --output json --task "summarize architecture and list highest-risk modules with evidence links" | tee analysis-run.json

Useful prompt patterns

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?

Outcome

After the run, you should have:

• analysis-run.json
• .akmon/audit/<session-id>.jsonl
• .akmon/evidence/<session-id>.json

Reviewer question this answers: "What did the analyst inspect, and is the summary traceable to a verifiable session?"

Anti-patterns

• Using broad write tasks during initial architecture discovery.
• Reporting "risk areas" without keeping the corresponding session evidence.

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.

MCP governance policy dimensions

In configured policy mode, MCP is governed by explicit server/tool rules:

[mcp.servers]
allow = ["github-prod"]
deny = ["*"]

[mcp.tools]
allow = ["search_issues"]
deny = ["*"]

This example allows exactly one server/tool pair and denies all others.

Fail-closed behavior:

• missing or malformed MCP context denies,
• ambiguous MCP context (same tool name from multiple servers) denies,
• parent policy modes without configured MCP rules deny.

Audit enrichment for MCP actions

Policy and MCP tool outcome audit rows include:

• mcp_server
• mcp_tool
• decision_reason (policy rows)

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.
• MCP call denied by policy: check [mcp.servers] and [mcp.tools] allow/deny rules, then inspect audit decision_reason.
• Unexpected fail-closed deny: ensure MCP tool names are unique across servers or scope policy to one server.

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.

Verification

akmon audit verify .akmon/audit/<session-id>.jsonl
akmon --output json audit verify .akmon/audit/<session-id>.jsonl

Exit codes:

• 0: chain valid
• 1: invalid/missing/tampered audit file

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).

Each JSONL row also includes tamper-evident chain metadata:

• schema_version ("audit_chain.v1"),
• event_index,
• prev_hash,
• event_hash,
• optional session_final_hash on the final row.

Example lines:

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

Downstream parsers should deserialize each line as AuditChainRecord and read the original event payload from .event (flattened fields like event_kind remain present in JSON).

For replay workflows, pair this audit chain with CLI JSON output replay_metadata hashes (policy_hash, config_hash, tool_registry_hash, optional prompt_assembly_hash) to validate run prerequisites before replaying.

Akmon evidence artifacts (.akmon/evidence/<session-id>.json) include the linked audit_log_path, audit validation result, and final chain hash so CI can verify replay + audit + tool/file outcomes together.

Migration note

If you previously parsed each line as plain AuditEvent, migrate to AuditChainRecord and validate:

• schema_version == "audit_chain.v1"
• monotonic event_index
• prev_hash/event_hash chain integrity
• session_final_hash only on the final record

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.
• Chain verification failure: a line was modified/reordered or truncated; re-export the original audit artifact and verify with the same file bytes.
• Secrets concern: logs should not contain API keys; if they appear, rotate keys and report immediately.

See also security model and cost guide.

Policy Profiles & Packs

Akmon supports enterprise policy rollout with reusable profiles and composable packs.

Built-in profiles

• dev: read-friendly, controlled writes, restricted shell/network
• staging: stricter write/shell/network posture than dev
• prod: highly restrictive, explicit-deny posture for side effects

Profiles map to the existing PolicyConfig schema (filesystem, shell, network, tools).

Policy packs

Policy packs are local TOML/JSON policy files layered on top of a selected profile.

Default discovery path:

.akmon/policy-packs/*.toml
.akmon/policy-packs/*.json

Additional packs can be added with repeatable CLI flags:

akmon --policy-pack .akmon/policy-packs/org.toml --policy-pack .akmon/policy-packs/team.toml --task "..."

Malformed selected packs fail closed with an explicit error.

Deterministic precedence

Effective policy merge order:

1. built-in profile
2. packs
3. project-local policy (.akmon/policy.toml or .akmon/policy.json)
4. CLI override (--policy-override)

Within each layer, list fields append and deduplicate while keeping the last occurrence, so higher-precedence layers keep later rule order.

Inspect effective policy

Use:

akmon policy show-effective --profile staging --policy-pack .akmon/policy-packs/org.toml
akmon --output json policy show-effective --profile prod

This prints the final merged policy and the exact source order used.

Rollout guidance

Typical enterprise rollout:

1. Start with dev + narrow team packs.
2. Tighten shell/network/tool scope in staging.
3. Lock production automation to prod + audited minimal override pack.
4. Enforce evidence/SLO checks in CI after policy changes.

Evidence Artifact

Documented for Akmon 2.0.0.

Who this is for

Developers and reviewers who need portable run evidence for CI and audit workflows.

What you will have at the end

• A clear model of what Akmon records in evidence artifacts.
• Commands to validate artifact integrity and enforce reliability gates.

Prerequisites

• A completed headless run (akmon --task ...) that emitted artifacts.

Steps

1. Run a headless session to produce evidence.

akmon --task "run tests and summarize failures" --output json --yes | tee run.json

2. Locate the evidence artifact path.

Akmon writes a deterministic evidence artifact per successful/budget-stopped headless run:

.akmon/evidence/<session-id>.json

You can override the location with --evidence-path <path>.

3. Verify evidence and linked audit chain:

akmon evidence verify .akmon/evidence/<session-id>.json

Why it exists

The artifact is designed for CI/PR automation and links:

• replay metadata (replay_metadata hashes),
• audit-chain integrity (audit.audit_chain_valid, session_final_hash),
• policy decision summary,
• tool execution timeline + aggregates,
• reliability/SLO metrics,
• touched files and verification outcomes.

Schema version

Artifacts include:

• evidence_schema_version (currently evidence.v1)

Consumers should validate schema version before strict parsing.

Example

{
  "evidence_schema_version": "evidence.v1",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "generated_at": "2026-04-20T12:34:56.000Z",
  "replay_metadata": {
    "hash_algorithm": "sha256",
    "provider_name": "ollama",
    "model_id": "llama3.2",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "policy_hash": "...",
    "config_hash": "...",
    "tool_registry_hash": "...",
    "prompt_assembly_hash": "..."
  },
  "audit": {
    "audit_log_path": ".akmon/audit/550e8400-e29b-41d4-a716-446655440000.jsonl",
    "audit_chain_valid": true,
    "session_final_hash": "..."
  },
  "policy": {
    "allow": 8,
    "deny": 1,
    "prompted": 2,
    "decision_samples": ["allow:read_file:..."]
  },
  "tools": {
    "timeline": [{"name": "read_file", "success": true, "message": "ok"}],
    "total": 1,
    "success": 1,
    "failure": 0
  },
  "files_touched": ["src/main.rs"],
  "verification": {
    "outcomes": [],
    "unavailable_reason": "verification commands not collected in this run"
  },
  "reliability_metrics": {
    "tool_calls_total": 1,
    "tool_calls_success": 1,
    "tool_calls_failure": 0,
    "tool_latency_ms_total": 14,
    "tool_latency_ms_avg": 14,
    "tool_latency_ms_p95": 14,
    "policy_denials_total": 0,
    "retries_total": 0,
    "timeouts_total": 0
  },
  "notes": []
}

Validation

akmon evidence verify checks schema support, replay metadata shape, linked audit-chain integrity, and session hash consistency.

Exit codes:

• 0: evidence valid
• 1: evidence invalid/missing/tampered

Verification

SESSION_ID="$(jq -r '.session_id' run.json)"
akmon evidence verify ".akmon/evidence/${SESSION_ID}.json"

Expected result: command exits 0 and reports valid schema/session linkage.

Enforcing SLOs in CI

You can enforce reliability guardrails directly against evidence:

akmon slo verify .akmon/evidence/<session-id>.json --strict

Example GitHub Actions step:

- name: Enforce Akmon SLO guardrails
  run: |
    akmon slo verify .akmon/evidence/${SESSION_ID}.json \
      --thresholds .github/akmon/slo.toml \
      --strict

Trend/regression check against prior evidence history:

- name: Detect reliability regressions
  run: |
    akmon slo trend .akmon/evidence/${SESSION_ID}.json \
      --baseline-dir .akmon/evidence/history \
      --window 20 \
      --strict

Troubleshooting

• If evidence verify fails, confirm artifact path and JSON validity.
• If session linkage errors appear, ensure audit/evidence files are from the same session.
• If SLO gates fail, inspect thresholds and reliability_metrics fields before relaxing policy.

Policy provenance and hash impact

Evidence keeps replay metadata policy_hash, which is computed from the effective runtime policy mode/config after profile/pack/local/override merge. Any change in selected profile or pack contents deterministically changes policy_hash, enabling CI/PR systems to detect policy-governance drift even when behavior changes are subtle.

Migration note

Treat evidence_schema_version as required for parsers and reject unknown versions. reliability_metrics is additive and stable-keyed for CI automation.

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.

For automation and CI, file-modifying tools also expose dry_run validation:

• run patch / apply_patch / edit / write_file with dry_run: true,
• inspect returned file_change_set (mode: "dry_run", summary, risk, per-file changes),
• execute the same tool call without dry_run only when risk and diffs are acceptable.

Policy-as-code (Configured)

Configured policy mode supports declarative allow/deny rules for:

• filesystem read/write paths,
• shell command prefixes,
• network domains,
• tool names.
• MCP server names and MCP tool names.

Evaluation is deterministic: explicit deny wins, and the most specific matching rule is selected within each rule list.

MCP governance hardening (fail-closed)

MCP tool calls are now governed by dedicated policy dimensions:

• mcp.servers.allow / mcp.servers.deny
• mcp.tools.allow / mcp.tools.deny

Execution posture is fail-closed:

• missing MCP context (server/tool) denies,
• ambiguous MCP context denies,
• parent policy modes without configured MCP rules deny,
• explicit deny rules win over allow matches.

MCP calls still pass normal permission checks after MCP policy approval (no bypass path).

Enterprise policy profiles and packs

Akmon supports reusable policy governance inputs for org rollout:

• built-in profiles (dev, staging, prod),
• policy packs loaded from .akmon/policy-packs/*.toml|json,
• project-local policy file (.akmon/policy.toml or .akmon/policy.json),
• optional CLI override (--policy-override).

Precedence is explicit and deterministic:

profile < packs < project-local < CLI override

This enables staged hardening from development to production without changing the underlying permission classes.

Recommended posture:

• dev: fast local iteration with controlled side effects.
• staging: tighter shell/network/tool posture for pre-prod automation.
• prod: explicit-deny heavy posture with minimal mutation surface.

Nested/subagent safety ceiling

spawn_subagent now runs under a strict parent permission ceiling:

• nested sessions never seed broad "allow all writes" approvals,
• parent interactive mode is downgraded to read-oriented nested execution (no implicit side effects),
• tool eligibility is pre-filtered with policy evaluation using tool-name context,
• side-effect decisions still pass through normal permission checks at dispatch time.

This closes the class of escalation where a nested run could gain broader write/shell/network rights than the parent session posture.

Before:

• nested bootstrap pre-seeded broad interactive allow replies,
• side-effect tools could be available in nested runs even when parent posture was read-only.

After:

• nested runs fail closed when confirmations cannot be satisfied safely,
• nested tool access is a subset of parent policy capability.

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.

Reliability metrics are observability only

Run/evidence reliability counters (tool success rates, denials, retries, timeouts) are for operational visibility and SLO monitoring. They do not grant permissions and do not bypass policy enforcement.

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.

Reliability & SLO Metrics

Akmon emits lightweight run-level reliability metrics in headless JSON output and evidence artifacts.

Why this exists

These counters make runs measurable in CI and operations workflows without adding heavy tracing overhead.

Metrics schema

reliability_metrics includes:

• tool_calls_total
• tool_calls_success
• tool_calls_failure
• tool_latency_ms_total
• tool_latency_ms_avg
• tool_latency_ms_p95 (nullable when no tool calls occurred)
• policy_denials_total
• retries_total
• timeouts_total

Starter SLO targets

Use these as a baseline, then tune by repo/workflow:

• tool success rate >= 95% (tool_calls_success / tool_calls_total)
• timeout rate < 2% of tool calls for stable pipelines
• policy denial ratio should be predictable for your mode:
  • higher in strict/read-only modes is expected,
  • sudden spikes in implementation mode should be investigated

CI alerting pattern

Run with JSON output:

akmon --output json --task "..." > run.json

Example checks with jq:

jq -e '
  .status == "completed"
  and (
    .reliability_metrics.tool_calls_total == 0
    or (.reliability_metrics.tool_calls_success / .reliability_metrics.tool_calls_total) >= 0.95
  )
  and .reliability_metrics.timeouts_total < 3
' run.json

Or enforce directly with built-in guardrails:

akmon slo verify run.json --thresholds .akmon/slo.toml --strict

Trend regression detection

Guard against quality drift using historical baseline artifacts:

akmon slo trend .akmon/evidence/current.json \
  --baseline-dir .akmon/evidence/history \
  --window 20 \
  --strict

akmon slo trend selects the last N valid baseline samples deterministically, then compares current metrics to baseline aggregates (median for rates, mean for totals/latency deltas).

Scope and limitations

• retries_total tracks session-level continuation retries currently visible in akmon-query.
• timeouts_total tracks timeout outcomes visible in session/model/tool paths.
• Provider-internal retry loops that are fully hidden behind provider clients are not counted separately.

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.

For local models, "free token cost" still carries operational tradeoffs:

• cold-start latency can be significant on first request,
• smaller local context windows can trigger no-output/context-overflow failure modes,
• tool-calling reliability varies by model family.

Use Akmon's local status hints and remediation guidance (/clear, ollama ps, model switch) to recover quickly.

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.

For automated runs, pair budget caps with evidence/SLO checks:

akmon --yes --output json --max-budget-usd 1.50 --task "..." | tee run.json
akmon slo verify run.json --thresholds .akmon/slo.toml

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

Documented for Akmon 2.0.0.

Who this is for

Engineers and CI maintainers who need an accurate command surface overview before using command-specific reference pages.

What you will have at the end

• The canonical top-level command layout.
• Common global flags and where to inspect exhaustive flags.
• Pointers to per-command reference pages for stable automation.

Prerequisites

1. Akmon installed and runnable (akmon --version).
2. A project repository for interactive or headless runs.

Steps

1. Inspect top-level help.

akmon --help

Expected result: all current global options and subcommands from clap output.

2. Use interactive mode (default) or headless mode (--task) as needed.

# Interactive TUI
akmon

# Headless run
akmon --task "run tests and summarize failures" --output json --yes

3. Use command-specific help for exact flags before scripting.

akmon verify --help
akmon inspect --help
akmon bundle export --help
akmon bundle import --help
akmon replay --help

Verification

Run a no-side-effect check on command availability:

akmon --help
akmon config --help
akmon policy --help
akmon slo --help

Expected result: commands parse and help exits 0.

Troubleshooting

• If a command in this page differs from your binary, treat akmon --help as source of truth.
• For provider or auth routing confusion, run akmon config explain-provider.
• For failed provider setup, run akmon doctor providers.

Top-level subcommands (v2.0.0)

• chat
• init
• new
• config
• doctor
• audit
• evidence
• slo
• policy
• scout
• spec
• import
• export
• bundle
• verify
• inspect
• redact
• diff
• replay

Common global flags

• --task <TEXT>: headless task run.
• --model <MODEL>: active model id.
• --yes: auto-approve read-only tools.
• --output <text|json>: output format.
• --audit-log <PATH>: override audit JSONL output path.
• --evidence-path <PATH>: override evidence JSON path.
• --policy-profile <dev|staging|prod>: select built-in policy profile.
• --policy-pack <PATH>: add policy pack (repeatable).
• --policy-override <PATH>: highest-precedence override file.
• --web-fetch: enable web_fetch tool.
• --yes-web: auto-approve web_fetch to allowed public URLs.
• --mcp-server <URL>: register MCP tools from remote server (repeatable).
• --index: load/build semantic index.
• --plan: read-only planning mode.
• --architect: two-phase planner+implementation mode.
• --planner-model <MODEL>: planner model override.
• --continue: resume last project session.
• --session <ID_OR_PREFIX>: resume specific session.
• --name <TEXT>: session display name.
• --max-budget-usd <USD>: headless spend cap.
• --add-dir <DIR>: add sandbox directory (repeatable).
• --dossier <PATH>: inject scout dossier context.
• --fallback-model <MODEL>: fallback on repeated 429/529 (headless).

Command-specific references

• akmon verify
• akmon inspect
• akmon bundle export
• akmon bundle import
• akmon redact
• akmon replay
• akmon diff

Trust and governance commands

akmon audit verify <PATH>

Verify tamper-evident audit chain integrity.

akmon audit verify .akmon/audit/<session-id>.jsonl
akmon --output json audit verify .akmon/audit/<session-id>.jsonl

Exit codes:

• 0: valid chain
• 1: invalid/missing audit file

akmon evidence verify <PATH>

Verify evidence schema + replay metadata shape + linked audit consistency.

akmon evidence verify .akmon/evidence/<session-id>.json
akmon --output json evidence verify .akmon/evidence/<session-id>.json

Exit codes:

• 0: valid evidence
• 1: invalid/missing evidence

akmon slo verify <PATH>

Evaluate run/evidence reliability metrics against thresholds.

akmon slo verify .akmon/evidence/<session-id>.json --strict
akmon slo verify run.json --thresholds .akmon/slo.toml
akmon --output json slo verify run.json --min-tool-success-rate 0.95

Exit codes:

• 0: all enabled checks pass
• 1: threshold violation(s)
• 2: invalid input/config

akmon slo trend <CURRENT_PATH>

Compare current metrics vs historical baseline window.

akmon slo trend .akmon/evidence/current.json \
  --baseline-dir .akmon/evidence/history \
  --window 20 \
  --strict

akmon --output json slo trend run.json \
  --baseline-file .akmon/evidence/r1.json \
  --baseline-file .akmon/evidence/r2.json

Exit codes:

• 0: no regression violations
• 1: regression violations (or strict-mode skipped checks)
• 2: invalid input/config/baseline setup

akmon policy show-effective

Print effective merged configured policy and source layers.

akmon policy show-effective --profile staging
akmon policy show-effective --profile prod --policy-pack .akmon/policy-packs/org.toml
akmon --output json policy show-effective --policy-override /tmp/policy.toml

Exit codes:

• 0: command succeeded (with or without configured policy sources)
• 1: merge/load error (invalid pack, ambiguous local policy, parse failure)

akmon config explain-provider

Print a deterministic provider resolution trace for the effective CLI model and merged ~/.akmon/config.toml. This command is explainability only: it does not change routing rules and mirrors the same selection as LlmConnectConfig::resolve.

akmon config explain-provider
akmon config explain-provider --json
akmon --output json config explain-provider

The JSON object includes selected_provider, selected_reason, model_id, optional resolution_error, and candidates[] (each with provider, eligible, reason, missing_prerequisites, priority_order). Secrets are never echoed—only named prerequisites.

Pair this with akmon doctor providers when debugging: explain-provider answers “which branch won and why,” while doctor checks reachability and credential sanity.

akmon doctor providers

Run provider preflight diagnostics with actionable remediation hints.

akmon doctor providers
akmon --output json doctor providers

The report includes a provider_resolution block (same schema as akmon config explain-provider) so you can correlate routing decisions with health checks in one JSON payload.

Checks include:

• key/env presence (masked),
• endpoint format sanity,
• endpoint reachability (where applicable),
• auth mode mismatch hints,
• model hint availability probes where feasible.

Exit codes:

• 0: active/required provider health checks passed
• 1: critical misconfiguration or unreachable required provider

akmon scout --task "..."

Run bounded, read-only repository scouting and write a structured dossier.

akmon scout --task "find MCP policy enforcement path"
akmon scout --task "TUI state boundaries" --max-files 300 --out .akmon/context/tui-scout.json
akmon --output json scout --task "docs CI checks"

Key flags:

• --task: required scout question.
• --max-files: upper bound for scanned files (default 200).
• --out: dossier output path (default .akmon/context/scout-<timestamp>.json).
• --max-budget-usd: optional cap (scout itself has zero model spend).

Exit codes:

• 0: dossier generated and written successfully
• 1: scan or write failure
• 2: invalid input (empty task, invalid bounds, invalid budget)

--dossier <PATH> ingestion

Use a previously generated dossier to seed implementation context:

akmon scout --task "provider routing and doctor coverage" --out .akmon/context/providers.json
akmon --dossier .akmon/context/providers.json --task "implement provider explainability"

Invalid or malformed dossier files fail fast before session start.

Headless JSON output shape

Example (akmon --output json --task "..."):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "exit_reason": "completed",
  "result": "Done",
  "tool_calls": 6,
  "files_written": ["src/main.rs"],
  "usage": {
    "total_input_tokens": 12100,
    "total_output_tokens": 830,
    "total_cache_read_tokens": 2100
  },
  "cost_usd": 0.04,
  "replay_metadata": {
    "hash_algorithm": "sha256",
    "provider_name": "ollama",
    "model_id": "llama3.2",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "policy_hash": "...",
    "config_hash": "...",
    "tool_registry_hash": "...",
    "prompt_assembly_hash": "..."
  },
  "reliability_metrics": {
    "tool_calls_total": 6,
    "tool_calls_success": 6,
    "tool_calls_failure": 0,
    "tool_latency_ms_total": 132,
    "tool_latency_ms_avg": 22,
    "tool_latency_ms_p95": 40,
    "policy_denials_total": 0,
    "retries_total": 0,
    "timeouts_total": 0
  },
  "provider_resolution": {
    "selected_provider": "ollama",
    "selected_reason": "Resolution succeeded: selected provider `ollama` (same outcome as `LlmConnectConfig::resolve`).",
    "model_id": "llama3.2",
    "candidates": [
      {
        "provider": "bedrock",
        "eligible": false,
        "reason": "Skipped: Bedrock is considered only when `--bedrock` is set or `AWS_ACCESS_KEY_ID` is present.",
        "priority_order": 1
      }
    ]
  }
}

The provider_resolution field is additive (automation may ignore it). When present, candidates lists every resolver branch in priority order with human-readable reasons; it is safe to log (no secret values).

Tool output parsing notes

When a run executes file-modifying tools (write_file, edit, patch, apply_patch), successful tool outputs are JSON strings that include a file_change_set payload:

• type: "file_change_set"
• mode: "applied" or mode: "dry_run"
• changes[] + summary + risk

CI consumers should parse changes[] as canonical and may continue accepting files[] as a backward-compatible alias.

Evidence output location

By default, headless runs write:

.akmon/evidence/<session-id>.json

Override with:

akmon --task "..." --evidence-path /tmp/run-evidence.json

akmon verify

Documented for Akmon 2.0.0.

Who this is for

Reviewers, CI engineers, and operators validating recorded session integrity before trusting artifacts.

What you will have at the end

• A pass/fail integrity decision for one session UUID.
• Optional JSON output suitable for CI gates.

Prerequisites

• A session UUID from a completed Akmon run.
• Access to the journal directory (default or custom).

Steps

1. Run verification on a session UUID.

akmon verify <session-id>

2. Use JSON for automation.

akmon verify <session-id> --format json

3. Use optional flags as needed:
   • --journal <PATH>
   • --format <human|json> (default human)
   • --verbose

Exit codes

Verification

akmon verify <session-id> --format json | jq '.passed'

Expected result: true for an intact session; non-zero exit with violations/errors otherwise.

What verify checks (AGEF Section 13 alignment)

• Parent chain integrity: each non-start event points to the expected prior event.
• Sequence integrity: event sequences are contiguous (0..n-1).
• Event hash recompute: canonical CBOR event bytes hash to stored event hashes.
• Object presence: each referenced object hash resolves in object storage.
• Object byte re-hash: resolved object bytes hash back to referenced object hashes.
• Head consistency: stored session head equals the terminal event hash.
• SessionEnd invariants: exactly one SessionEnd, and it is terminal.

Troubleshooting

• exit 2: invalid CLI usage; re-check akmon verify --help.
• exit 3: session/journal access error; verify UUID and --journal path.
• exit 1: integrity violation found; inspect JSON violations for exact category.

See also

• AGEF specification
• akmon inspect
• akmon replay

akmon inspect

Synopsis

Inspect one on-disk session journal and display its event contents.

akmon inspect <session-id> [OPTIONS]

akmon inspect <session-id> \
  [--journal <path>] \
  [--format <human|json>] \
  [--verbose] \
  [--resolve] \
  [--binary <meta|hex|base64>]

Description

akmon inspect reads a stored session from the local Akmon journal and prints the event timeline with kind-specific fields. It is a read-only inspection command: no session data is created, modified, or deleted.

Use it when you need to review what happened in a session, debug tool/model behavior, or prepare audit evidence review. A reviewer can use inspect to see exactly what was said, what provider attempts occurred, what tools ran, and which hashes connect each step.

akmon inspect and akmon verify are complementary. inspect shows contents; verify checks integrity and tamper evidence. In v2.0.0 both are substrate-only commands and both target one session by UUID.

Arguments

<session-id> (required)

Hyphenated UUID assigned at AgentSession construction.

Example:

akmon inspect 550e8400-e29b-41d4-a716-446655440000

Options

--journal <path> (optional)

Journal directory to inspect. If omitted, Akmon resolves the default per-user journal path ($XDG_STATE_HOME/akmon/journal, per D-04).

--format <human|json> (optional, default: human)

Select output format:

• human: terminal-friendly multi-line output.
• json: machine-readable InspectReportV1.

--verbose (optional)

Expands human output from summary to full detail: full hashes, parent hashes, emitted_at, and full provider attempt records. Has no effect on JSON output (JSON always includes full detail).

--resolve (optional)

Resolves referenced object hashes from local object storage and includes content-aware renderings (UTF-8 text or binary metadata). Without --resolve, inspect shows hash references only.

--binary <meta|hex|base64> (optional, default: meta)

Display mode for non-UTF-8 resolved content:

• meta: <binary, N bytes, hash: ...>
• hex: first 64 bytes as lowercase hex pairs, then truncation footer if needed
• base64: first 128 base64 characters, then truncation footer if needed

hex and base64 require --resolve. meta can be provided without --resolve, but has effect only when objects are resolved.

Exit codes

Output formats

Human (default, summary)

session: 550e8400-e29b-41d4-a716-446655440000
events: 4
journal: /home/user/.local/state/akmon/journal

[0] SessionStart hash=8b2a3f7c...
  cwd_hash: 1f3a5b2e...
  config_hash: 4e1d92a8...

[1] UserTurn hash=5c9d1e41...
  prompt_hash: d7ac9f11...

[2] ProviderCall hash=9a7f220e...
  provider: anthropic-claude
  attempts: 1 (1 Success)
  stream_hash: 0f23cd18...

[3] AssistantTurn hash=31b8f501...
  message_hash: 69ea4bd9...

Human (verbose)

[2] ProviderCall hash=9a7f220e7fd7f52a0b9c6ec8337f9c0da52dc1a4f8e96767bfac44e5f3c4f2d0
  parent: 5c9d1e41c9eb7b468b3f31c30d0495a6708ec61862db2f3ea1df1c53de2b9581
  emitted_at: 2026-01-15T14:32:10.123Z
  provider: anthropic-claude
  attempts:
    [1] status=Success started=14:32:10.123 ended=14:32:12.234
      request_hash: 0a4d4c95b4...
      response_hash: a4fbc71e2c...
      stream_hash: 0f23cd18b1...

Human (resolve, text)

[1] UserTurn hash=5c9d1e41...
  prompt_hash: d7ac9f11...
  prompt:
    | how do I configure the policy engine to allow shell
    | commands matching a specific prefix without prompting
    | each time?

Human (resolve, binary)

[4] ToolCall hash=cc77e1ab...
  tool: read_file
  input_hash: a1b2c3d4...
  input: <binary, 1024 bytes, hash: a1b2c3d4...>
    | a1 b2 c3 d4 e5 f6 ... (truncated, 960 more bytes)

JSON (--format json)

{
  "akmon_version": "2.0.0",
  "agef_version": "0.1.1",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "journal_path": "/home/user/.local/state/akmon/journal",
  "events": [
    {
      "sequence": 1,
      "event_hash": "5c9d1e41c9eb7b468b3f31c30d0495a6708ec61862db2f3ea1df1c53de2b9581",
      "parent_hashes": [
        "8b2a3f7c1ef0ea7e80f772f8f84f86b16f5527cd51ff8b0a464f157c4cd5c757"
      ],
      "emitted_at": "2026-01-15T14:32:09.942Z",
      "kind": {
        "type": "user_turn",
        "prompt_hash": "d7ac9f11f8069ce39f5df1863fcef84f8f46406fdb6f866f9317dbf2ca6fcb53",
        "prompt_text": "how do I configure the policy engine?",
        "prompt_size": 43
      }
    }
  ]
}

InspectReportV1

• akmon_version: Akmon CLI version that produced this report.
• agef_version: AGEF specification version implemented by the substrate.
• session_id: session UUID (hyphenated lowercase).
• journal_path: resolved absolute journal directory used.
• events: array of InspectEvent in sequence order.

InspectEvent

• sequence (u64): event sequence number (0-indexed).
• event_hash (string): lowercase hex-encoded event hash.
• parent_hashes (string[]): lowercase hex-encoded parent hashes.
• emitted_at (string): ISO 8601 UTC timestamp.
• kind (InspectEventKind): tagged event payload.

InspectEventKind

kind is a tagged enum with type discriminator (snake_case):

• session_start: cwd_hash, config_hash, and with --resolve optional cwd_text/cwd_size, config_text/config_size
• user_turn: prompt_hash, and with --resolve optional prompt_text/prompt_size
• provider_call: provider_id, attempts, stream_hash, and with --resolve optional stream_text/stream_size
• tool_call: tool_id, input_hash, output_hash, side_effects_hash, and with --resolve optional input_text/input_size, output_text/output_size, side_effects_text/side_effects_size
• retrieval_call: index_id, query_hash, results_hash, and with --resolve optional query_text/query_size, results_text/results_size
• permission_gate: policy_id, decision, context_hash, and with --resolve optional context_text/context_size
• assistant_turn: message_hash, tool_calls_hash, and with --resolve optional message_text/message_size, tool_calls_text/tool_calls_size
• session_end: summary_hash, and with --resolve optional summary_text/summary_size

InspectAttempt

• attempt_number (u32): 1-indexed attempt number.
• status (string): attempt status name.
• started_at (string): ISO 8601 UTC timestamp.
• ended_at (string): ISO 8601 UTC timestamp.
• request_hash (string): lowercase hex-encoded request hash.
• response_hash (string | null): response hash when present.
• stream_hash (string | null): stream transcript hash when present.
• error_message (string | null): provider error message when present.
• request_text/request_size, response_text/response_size, stream_text/stream_size: present only with --resolve and only when content is available.

InspectError

Infrastructure failures use this JSON shape:

{
  "akmon_version": "2.0.0",
  "category": "session_not_found",
  "error": "cannot open journal ...: session not found: 550e8400-e29b-41d4-a716-446655440000"
}

• akmon_version: Akmon CLI version that produced the error.
• category: one of:
  • journal_not_found
  • session_not_found
  • inspect_infrastructure_error
• error: human-readable diagnostic message.

Examples

1) Inspect a session (default summary)

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000

2) Verbose inspection

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000 --verbose

3) Show resolved content (text and binary metadata)

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000 --resolve

4) Show binary payloads as hex preview

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000 --resolve --binary hex

5) JSON output for CI

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000 --format json | jq '.events | length'

6) JSON with resolved user text

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000 --format json --resolve \
  | jq '.events[] | select(.kind.type == "user_turn") | .kind.prompt_text'

7) Custom journal path

$ akmon inspect 550e8400-e29b-41d4-a716-446655440000 --journal /tmp/my-journal

What inspect shows

inspect can display these event kinds:

• SessionStart
• UserTurn
• ProviderCall (including attempt details)
• ToolCall
• PermissionGate
• AssistantTurn
• SessionEnd
• RetrievalCall (if present in journal; reserved for future Akmon emission)

RetrievalCall support is included for forward compatibility with AGEF and v2.0 planning; Akmon v2.0.0 does not emit it in normal runs.

What inspect does not do

• It does not verify integrity or tamper evidence (akmon verify does that).
• It does not modify session state (read-only journal access).
• It does not fetch content from external systems (resolution reads only local journal object bytes).
• It does not decode domain-specific binary encodings beyond UTF-8 detection and preview rendering.

Programmatic / CI usage

• Use --format json and jq (or your parser) to query events by kind and field.
• Use exit codes (0/2/3) to handle success, usage issues, and missing journal/session cases.
• --resolve increases read cost with total resolved object size; skip when hashes are sufficient.
• Output is deterministic for the same session contents (covered by integration test t_inspect_output_stability).

See also

• akmon verify: ./verify.md
• AGEF specification: github.com/radotsvetkov/agef
• akmon export / akmon import (Item 4.3, coming)

akmon bundle export

Documented for Akmon 2.0.0.

Who this is for

Teams exporting a portable, verifiable session artifact for handoff, audit, or archive.

What you will have at the end

• A .akmon bundle generated from one journal session.
• Optional JSON metadata for automation.

Prerequisites

• Source session UUID.
• Access to source journal and write permission for output path.

Steps

akmon bundle export <session-id> [OPTIONS]

akmon bundle export <session-id> \
  [--output <path>] \
  [--journal <path>] \
  [--format <human|json>]

1. Export with defaults:

akmon bundle export <session-id>

2. Export to explicit path:

akmon bundle export <session-id> --output /path/to/audit.akmon

3. Use JSON in CI:

akmon bundle export <session-id> --format json

Exit codes

Verification

akmon bundle export <session-id> --format json | jq '.output_path'

Expected result: output path is returned and command exits 0.

Bundle format

An .akmon bundle is a tar.zst archive containing:

• manifest.json
• events.bin
• objects/<hex>

Troubleshooting

• If export fails with output-exists error, choose a new --output path.
• If export fails with session/journal errors, verify UUID and --journal location.
• Export does not replace integrity checks; run akmon verify before export when required.

See also

• akmon bundle import: ./bundle-import.md
• akmon verify: ./verify.md
• akmon inspect: ./inspect.md
• AGEF specification

akmon bundle import

Documented for Akmon 2.0.0.

Who this is for

Teams validating and ingesting portable .akmon bundles into local journals.

What you will have at the end

• A verified bundle (--verify-only) or imported session.
• Clear handling for collisions and archive validation failures.

Prerequisites

• Path to a .akmon bundle file.
• Write access to target journal if ingesting.

Steps

akmon bundle import <bundle-path> [OPTIONS]

akmon bundle import <bundle-path> \
  [--journal <path>] \
  [--format <human|json>] \
  [--verify-only] \
  [--allow-extra-files] \
  [--rename-to <NEW_UUID>]

1. Validate bundle only (no local writes):

akmon bundle import /path/to/audit.akmon --verify-only

2. Import into journal:

akmon bundle import /path/to/audit.akmon

3. Resolve session-id collisions with rename:

akmon bundle import /path/to/audit.akmon --rename-to <new-uuid>

4. Use JSON output in CI:

akmon bundle import /path/to/audit.akmon --verify-only --format json

Exit codes

Verification

akmon bundle import /path/to/audit.akmon --verify-only --format json | jq '.passed'

Expected result: true for valid bundle, otherwise false with violations and exit 1.

Validation checks (AGEF alignment)

Import validation aligns with AGEF structural/integrity requirements, including:

• Manifest parse/schema-required fields
• events.bin frame decoding (length-prefixed canonical CBOR events)
• Event hash-chain integrity
• Object closure (all referenced hashes present)
• Object byte re-hash (bytes match hash key)
• Head consistency (manifest.session.head matches terminal event hash)
• Session boundary invariants (SessionStart first, SessionEnd terminal)
• Sequence continuity (0..n-1)
• Strict unknown-content handling by default (unknown event tags/statuses/extra archive files rejected unless flags permit)

Troubleshooting

• If import exits 2 for collision, rerun with --rename-to <NEW_UUID>.
• If verify-only exits 1, inspect JSON violations categories.
• If import exits 3, check bundle path, journal permissions, and disk availability.

See also

• akmon bundle export: ./bundle-export.md
• akmon verify: ./verify.md
• akmon inspect: ./inspect.md
• AGEF specification

akmon redact

Documented for Akmon 2.0.0.

Who this is for

Teams generating sanitized derivative bundles for external review without exposing sensitive object content.

What you will have at the end

• A derivative .akmon bundle with selected objects replaced by redaction sentinels.
• A reproducible command trail with explicit rationale (--reason).

Prerequisites

• Source session UUID.
• Object hashes to redact (typically found via akmon inspect --resolve).
• Writable destination path for --output.

Steps

akmon redact <session-id> [OPTIONS]

akmon redact <session-id> \
  --output <path> \
  --object <hash> [--object <hash> ...] \
  --reason <text> \
  [--journal <path>] \
  [--format <human|json>]

1. Create sanitized derivative bundle:

akmon redact <session-id> \
  --output sanitized.akmon \
  --object <object-hash> \
  --reason "PII removal"

2. For multiple objects, repeat --object.

3. Verify derivative bundle before sharing:

akmon bundle import sanitized.akmon --verify-only

Exit codes

Verification

akmon redact <session-id> --output sanitized.akmon --object <object-hash> --reason "compliance" --format json | jq '.objects_redacted_count'

Expected result: positive redacted-object count and exit 0.

Sentinel format

Redacted objects are replaced by canonical-CBOR sentinel objects with this payload:

{
  "akmon_redacted": true,
  "original_hash": "<hex of original>",
  "original_size": 1024,
  "reason": "<text from --reason>",
  "redacted_at": "<RFC3339 timestamp>"
}

Troubleshooting

• If output path exists, choose a new --output target.
• If --object is rejected, confirm lowercase hex hash and that it is referenced in source session.
• Redaction does not verify source integrity automatically; run akmon verify <session-id> first when required.

See also

• akmon verify
• akmon inspect
• akmon bundle export
• akmon bundle import
• AGEF specification

akmon replay

Documented for Akmon 2.0.0.

Who this is for

Engineers replaying recorded sessions to detect divergences and regression behavior.

What you will have at the end

• A replay pass/fail report (default or strict mode).
• Optional persisted replay session in a target journal.

Prerequisites

• Source session UUID.
• Journal access to source session.

Steps

akmon replay <session-id> [OPTIONS]

akmon replay <session-id> \
  [--journal <path>] \
  [--mode <default|strict>] \
  [--persist --persist-to <path>] \
  [--format <human|json>]

1. Run default replay:

akmon replay <session-id>

2. Use strict mode if you want tighter mismatch handling:

akmon replay <session-id> --mode strict

3. Use JSON in CI:

akmon replay <session-id> --format json

4. Persist replay output only with explicit target:

akmon replay <session-id> --persist --persist-to /path/to/replay-journal

Exit codes

Verification

akmon replay <session-id> --format json | jq '.passed'

Expected result: true for equivalent replay; false if divergences are detected.

Examples

1) Replay a session with default mode

$ akmon replay 550e8400-e29b-41d4-a716-446655440000

2) Replay in strict mode

$ akmon replay 550e8400-e29b-41d4-a716-446655440000 --mode strict

3) JSON output for CI

$ akmon replay 550e8400-e29b-41d4-a716-446655440000 --format json | jq '.passed'

4) Persist replay output in a target journal

$ akmon replay 550e8400-e29b-41d4-a716-446655440000 \
  --persist \
  --persist-to ./replay-journal

5) Replay from a non-default journal

$ akmon replay 550e8400-e29b-41d4-a716-446655440000 --journal /custom/journal

Troubleshooting

• If --persist fails, ensure --persist-to is provided and writable.
• If replay cannot load source data, validate --journal path and source session UUID.
• If replay fails with divergences, inspect JSON divergences for event-level mismatch details.
• For integrity-first workflow, run akmon verify <session-id> before replay.

See also

• akmon verify
• akmon inspect
• akmon bundle import
• CLI Reference
• AGEF specification

akmon diff

Synopsis

akmon diff <session-a> <session-b> [OPTIONS]

akmon diff 550e8400-e29b-41d4-a716-446655440000 6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  [--journal <path>] \
  [--resolve] \
  [--format <human|json>]

Description

akmon diff compares two recorded sessions in the same journal scope and reports structural and field-level divergences. Both UUIDs must exist under the selected journal directory (default: $XDG_STATE_HOME/akmon/journal unless --journal is set).

Use diff for evidence-side regression checks (two runs of the same workflow), replay validation (source session vs replayed session in one store), and audit explanations (“what changed between these two session heads?”).

Comparison is lockstep by event sequence. When event kinds or counts diverge, diff reports a structural break and stops further alignment for that pair.

Arguments

<session-a>, <session-b> (required)

Hyphenated UUIDs of the two sessions to compare.

Options

--journal <path> (optional)

Journal directory containing journal.redb for both sessions. If omitted, Akmon uses the default journal location.

--resolve (optional)

Dereference content hashes for comparable fields and attach byte-level summaries (resolved or resolved_skip_reason on each divergence in JSON). Without this flag, comparison uses hash and structural summaries only.

--format <human|json> (optional, default: human)

• human: terminal-oriented summary; divergences list is capped at 10 entries (same cap as akmon replay human output), with a footer pointing to JSON for the full list.
• json: DiffReportV1 as pretty-printed JSON on standard output.

Exit codes

Output formats

Human (default)

First lines mirror the replay report shape: command line, indented stats (mode, events compared, per-session event counts, divergence count, matches: yes|no). When comparison fails, optional structural break: and divergences: sections follow, with expected: / actual: lines per divergence. With --resolve, divergences may include resolved: byte summaries or resolve skipped: reasons.

JSON

Pretty-printed DiffReportV1 (schema owned by the akmon-diff crate). Suitable for CI ingestion and golden tests.

See also

• akmon replay — replay comparison and exit-code discipline aligned with diff
• akmon inspect — single-event inspection; --resolve preview rules are aligned with diff resolve mode

Phase 6 (Item 6.3). v2.0.0 ships CLI diff with human and JSON reporting, integration tests, and a single shared journal.redb open when loading both sessions so redb per-process locking is respected.

Slash Commands

Documented for Akmon 2.0.0.

In akmon chat, type / then command name. Use /help in-session as runtime source of truth.

Session & navigation

Project memory

Models

Planning & specs

Insight & diagnostics

Verification

Run akmon chat, then /help, and verify command list contains the expected set for your build.

Configuration reference

Documented for Akmon 2.0.0.

Who this is for

Operators and maintainers who need the exact supported keys in ~/.akmon/config.toml.

What you will have at the end

• A code-accurate list of user config keys and sections.
• Confirmed policy/SLO sections used by current CLI commands.

Prerequisites

• Akmon installed and runnable.

Steps

1. Resolve the active config file path.

akmon config path

2. Inspect current config safely.

akmon config show
akmon config show --json

3. Edit only supported keys listed below.

Top-level keys (AkmonGlobalConfig)

default_model = "llama3.2"
ollama_url = "http://localhost:11434"

# Provider credentials (prefer env vars in CI)
# anthropic_api_key = "sk-ant-..."
# openrouter_api_key = "sk-or-..."
# openai_api_key = "sk-..."
# groq_api_key = "gsk_..."
# azure_openai_endpoint = "https://.../chat/completions"
# azure_openai_api_key = "..."
# azure_api_version = "2024-02-01"
# openai_compatible_url = "http://127.0.0.1:1234/v1"
# openai_compatible_api_key = "..."

Core model keys

default_model = "llama3.2"
ollama_url = "http://localhost:11434"

Provider credentials can be set via env vars or config fields.

Architect defaults ([architect])

[architect]
planner_model = "llama3.2"

Display settings ([display])

[display]
theme = "auto" # auto | dark | light

MCP servers ([[mcp]])

[[mcp]]
name = "github"
url = "https://mcp.example.com"
enabled = true
scope = "user" # user | project

Policy governance ([policy])

[policy]
profile = "dev" # dev | staging | prod
packs = [".akmon/policy-packs/org.toml", ".akmon/policy-packs/team.toml"]

profile selects built-in defaults. packs adds extra policy layers.

Effective precedence:

1. selected built-in profile,
2. policy packs,
3. project-local policy (.akmon/policy.toml or .akmon/policy.json),
4. CLI override (--policy-override).

Within a layer, list fields append and deduplicate while keeping later precedence order.

Policy rule schema (PolicyConfig)

Policy packs/local/override files use the same rule schema:

[filesystem.read]
allow = ["src/**", "Cargo.toml", "README.md"]
deny = ["src/**/secrets/**"]

[filesystem.write]
allow = ["src/**", "tests/**"]
deny = [".git/**", "**/*.pem"]

[shell]
allow_prefixes = ["cargo ", "rustfmt "]
deny_prefixes = ["cargo publish", "rm -rf "]

[network]
allow_domains = ["api.github.com", "*.rust-lang.org"]
deny_domains = ["169.254.169.254", "*.internal.local"]

[tools]
allow = ["read_*", "search", "shell"]
deny = ["shell_force", "write_secret"]

[mcp.servers]
allow = ["github-prod", "jira-main"]
deny = ["*"]

[mcp.tools]
allow = ["search_*"]
deny = ["delete_*", "admin_*"]

Engine behavior is deterministic:

• explicit deny beats allow,
• most specific rule wins in a rule list,
• no matching allow means deny.

For MCP actions, fail-closed behavior also applies:

• malformed/missing MCP context denies,
• ambiguous MCP context denies,
• parent policy modes without configured MCP rules deny.

Reliability defaults ([slo] and [slo.trend])

[slo]
min_tool_success_rate = 0.95
max_timeout_rate = 0.02
max_tool_failure_rate = 0.05
max_retries_total = 3
max_timeouts_total = 2
min_tool_calls_total = 5

[slo.trend]
max_success_rate_drop_abs = 0.05
max_timeout_rate_increase_abs = 0.02
max_failure_rate_increase_abs = 0.03
max_retries_increase_ratio = 1.0
max_latency_avg_increase_ratio = 0.50
min_baseline_samples = 5

max_policy_denial_rate is supported by akmon slo verify CLI thresholds, but is not part of [slo] defaults in AkmonGlobalConfig.

Model estimates ([[model_estimates]])

[[model_estimates]]
pattern = "haiku-4-5"
context_window_tokens = 200000
input_per_million_usd = 1.0
output_per_million_usd = 5.0
cache_read_per_million_usd = 0.1
note = "Pricing/context hint for local estimation."

Verification

akmon config show --json
akmon policy show-effective --profile dev
akmon slo verify .akmon/evidence/<session-id>.json --strict

Expected result: config parses, policy can render effective configuration, and SLO settings are consumed.

Troubleshooting

• If akmon config show fails, validate TOML syntax and remove unknown keys.
• If policy packs fail to load, check file paths and TOML/JSON parse errors from akmon policy show-effective.
• If SLO commands fail on thresholds, check whether you are using CLI overrides vs [slo] defaults.

Release notes: v2.0.0

Why this release

Akmon v2.0.0 is the production-ready release positioning Akmon as the review-aware AI coding agent for regulated engineering. Every session is now a tamper-evident, content-addressed, replayable artifact suitable for audit, compliance evidence, and post-incident review.

Top user-facing wins

• akmon diff: structural and field-level comparison between two recorded sessions, with optional --resolve for byte-level content diffs.
• akmon replay: deterministic re-execution of recorded sessions against playback providers and tools, with strict and default comparison modes.
• akmon bundle: portable AGEF v0.1.1 session archives for evidence sharing across environments.
• akmon redact: compliance-driven content removal producing derivative bundles with sentinel objects.
• AGEF v0.1.1: Akmon is the reference implementation. Bundle format and session evidence structure are now spec-stable for downstream tooling.

Upgrade notes

v2.0.0 reads sessions written by v1.8.x. Sessions written by v2.0.0 may use the AGEF v0.1.1 schema and should not be downgraded to v1.8.x without verification.

No CLI flag breaks; existing scripts targeting akmon run, akmon audit, akmon evidence, akmon slo, and akmon doctor continue to work unchanged.

Verification checklist

# Confirm install
akmon --version  # should report 2.0.0

# Verify a clean session round-trip
akmon --yes --task "echo hello" --output json | tee run.json
akmon audit verify .akmon/audit/<session-id>.jsonl
akmon evidence verify .akmon/evidence/<session-id>.json

# Try the new diff command
akmon diff <session-a> <session-b>

Docs links

• Diff CLI reference
• Replay CLI reference
• Bundle CLI reference
• AGEF specification

Release notes: v1.8.2

Why this release

v1.8.2 is an operability and trust release: provider routing is fully explainable and diagnosable without changing resolver behavior. Introspection mirrors LlmConnectConfig::resolve() deterministically; no routing algorithm changes.

Top user-facing wins

1. Deterministic ProviderResolutionTrace — structured trace (selected_provider, selected_reason, model_id, ordered candidates[] with eligible, reason, missing_prerequisites, priority_order) matching the real resolver priority. Secrets are never echoed; only named prerequisites.
2. akmon config explain-provider — print the trace in the terminal or as JSON (--json on config, or global --output json).
3. akmon doctor providers — includes the same provider_resolution block in text and JSON alongside existing health checks.
4. Headless --output json — run summary JSON includes additive provider_resolution for automation (same schema as above).

Upgrade notes

• No routing or CLI semantics changes for provider selection; this release adds diagnostics only.
• Pair config explain-provider (why this branch won) with doctor providers (keys, endpoints, reachability).

Verification checklist

akmon config explain-provider
akmon config explain-provider --json
akmon doctor providers
akmon --output json doctor providers
# After a headless run with --output json, inspect provider_resolution on stdout

Docs links

• CLI reference
• Provider setup & troubleshooting
• Environment variables & resolver order

Release notes: v1.8.1

Why this release

v1.8.1 is a stability and operability hardening release focused on trustworthy day-2 operation: deterministic provider diagnostics, fail-closed MCP governance, docs reliability gates, internal TUI maintainability, and stronger local-model reliability behavior.

Top user-facing wins

1. Provider preflight command: akmon doctor providers with actionable remediation and CI-friendly exit codes.
2. MCP governance hardening with explicit server/tool policy dimensions and enriched audit context.
3. Deterministic docs quality checks in CI (mdBook, links, CLI snippets, JSON snippets, fixtures).
4. Local-model reliability improvements for Ollama (adaptive timeouts, unified status hints, clearer remediation).
5. TUI internal state decomposition that improves maintainability without UX/command changes.

Upgrade notes

• No CLI breaking changes in this release.
• For configured policy + MCP environments, define explicit [mcp.servers] and [mcp.tools] allow rules.
• For local-model-heavy workflows, warm models (ollama run <model>) before long tasks and use /clear when context becomes noisy.

Verification checklist

akmon doctor providers
akmon --output json doctor providers
akmon audit verify .akmon/audit/<session-id>.jsonl
akmon evidence verify .akmon/evidence/<session-id>.json
akmon slo verify .akmon/evidence/<session-id>.json --strict

Docs links

• CLI reference
• Provider setup
• Configuration
• MCP integration
• Security model

Release notes: v1.8.0

Why this release

v1.8.0 makes Akmon a practical trust runtime for AI-assisted engineering by combining policy governance, tamper-evident auditing, replay/evidence artifacts, and enforceable reliability gates into one operator workflow.

Top user-facing wins

1. Deterministic policy controls with reusable profiles/packs (dev, staging, prod).
2. Verifiable execution trail (akmon audit verify, akmon evidence verify).
3. Replay metadata for forensic reproducibility in structured output.
4. Reliability metrics exposed in run reports and evidence artifacts.
5. CI-ready guardrails (akmon slo verify and akmon slo trend).

Migration checklist

• Update audit parsers to AuditChainRecord (schema_version: "audit_chain.v1").
• Update run report parsers to accept additive replay_metadata and reliability_metrics.
• Validate evidence using evidence_schema_version.
• Adopt policy precedence model: profile < packs < local < CLI override.

Verification checklist

akmon --yes --output json --task "run tests and summarize failures" | tee run.json
akmon audit verify .akmon/audit/<session-id>.jsonl
akmon evidence verify .akmon/evidence/<session-id>.json
akmon slo verify .akmon/evidence/<session-id>.json --strict
akmon slo trend .akmon/evidence/<session-id>.json --baseline-dir .akmon/evidence/history --window 20 --strict

Tutorials

• Local-first developer flow (Ollama)
• CI headless governance flow
• Enterprise policy rollout

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).

Dry-run diff preview (file_change_set)

File-modifying tools support a deterministic diff payload that can be inspected before writes:

• patch and apply_patch support dry_run: true.
• write_file and edit also support dry_run: true for preview-first workflows.
• When dry_run is true, tools still run full validation and diff generation, but skip disk mutation.

file_change_set success payload shape:

• type: always file_change_set
• mode: applied or dry_run
• changes[]: canonical per-file diff entries (path, diff, lines_added, lines_removed, lines_changed)
• summary: aggregate line/file counts
• risk: heuristic risk classification (low, medium, high)
• files[]: backward-compatible alias of changes[]

Practical flow:

1. Run patch (or apply_patch) with dry_run: true.
2. Parse summary + risk and inspect each changes[i].diff.
3. Re-run the same call without dry_run to persist changes (mode: "applied").

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.

Scout workflow (read-only)

akmon scout is a bounded read-only analysis workflow that generates a context_scout.v1 dossier under .akmon/context/.

• Uses read signals only (filesystem listing/reading/search-like path analysis).
• Does not invoke write/edit/patch/apply_patch/shell side effects.
• Emits deterministic sorted sections (scanned_paths, key_entrypoints, candidate_files, related_tests) and explicit truncation indicators when bounds are hit.

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

Documented for Akmon 2.0.0.

Who this is for

Users configuring Akmon via environment (shell, CI, secret managers) instead of storing credentials in ~/.akmon/config.toml.

What you will have at the end

• A verified list of environment variables recognized by the current CLI/provider resolver.
• A clear provider-resolution order for debugging.

Prerequisites

• Akmon installed and runnable (akmon --help).

Steps

1. Export provider variables needed for your route.

Provider keys

ANTHROPIC_API_KEY
OPENROUTER_API_KEY
OPENAI_API_KEY
GROQ_API_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_API_KEY
AWS_ACCESS_KEY_ID          # Bedrock
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN          # optional
AWS_DEFAULT_REGION

2. Use CLI help to verify current env-backed flags.

akmon --help
akmon config --help
akmon doctor providers --help

3. Inspect effective routing decision:

akmon config explain-provider

Detection order (matches LlmConnectConfig::resolve)

Akmon evaluates providers in a fixed priority order (first successful branch wins). This is introspection-only documentation—the runtime resolver is unchanged when you run explain commands.

1. Amazon Bedrock if --bedrock is set or AWS_ACCESS_KEY_ID is present (requires loadable AWS credentials including AWS_SECRET_ACCESS_KEY).
2. Native Claude (claude-* without /) via ANTHROPIC_API_KEY or, if absent, OpenRouter with an anthropic/<model> slug when OPENROUTER_API_KEY is set.
3. OpenRouter for org/model ids containing / (requires OPENROUTER_API_KEY).
4. Azure OpenAI when both AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY are set (plus api-version).
5. OpenAI when OPENAI_API_KEY is set and the model id matches OpenAI chat heuristics (gpt-*, o1*, …).
6. Groq when GROQ_API_KEY is set and the model id matches Groq heuristics (llama*, mixtral*).
7. Custom OpenAI-compatible URL when --openai-compatible-url (or config) is set—requires a key for that branch.
8. Ollama heuristics for local-style model ids, else Ollama default fallback.

Use akmon config explain-provider to print the same order with per-branch reasons for your current model and env. Use akmon config show (masked) to inspect stored config.

Additional runtime variables used by Akmon

EDITOR            # used by `akmon config edit` and TUI edit flows
AKMON_DEBUG_GIT   # enables git root discovery debug logging

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.

Verification

akmon config show --json
akmon config explain-provider

Expected result: provider prerequisites are reported without printing raw secrets.

Troubleshooting

• If Bedrock is unexpectedly selected, check whether AWS_ACCESS_KEY_ID is set.
• If slash model IDs fail, ensure OPENROUTER_API_KEY is available.
• If Azure is partially configured, set both AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY.

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.

TUI state decomposition (akmon-tui)

TuiApp remains the composition root, but state is now split into focused internal modules under crates/akmon-tui/src/state/:

• composer: input buffer + cursor behavior (insert/paste/backspace/delete/left/right/submit),
• overlay_state: overlay/modal state, confirmation gate state, ask-followup state, slash autocomplete selection/suppression,
• session_telemetry: token/tool counters, touched files, and context-warning bookkeeping,
• provider_runtime: provider/runtime status such as provider label, run flags, iteration progress, stream cursor, and ollama probe.

Why this helps:

• lower regression risk by reducing mixed responsibilities in app.rs,
• easier targeted tests for state transitions,
• clearer ownership when adding new TUI logic without changing UX behavior.

This refactor is intentionally internal: behavior and command semantics stay the same while maintainability/testability improve.

Contributor guideline for TUI changes:

• put new input-edit semantics in state/composer.rs,
• put overlay transition rules in state/overlay_state.rs,
• put counters/usage accumulation in state/session_telemetry.rs,
• put runtime/provider status updates in state/provider_runtime.rs,
• keep TuiApp focused on orchestration and event routing.

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.