Kodiqa

The AI coding agent that runs anywhere — free locally with Ollama, or supercharged by 8 cloud APIs. One agent, every model, zero limits.

86 slash commands • 32 tools • lazy MCP tools • RAG search • custom personas • plugins • sub-agents • LSP • 5 themes

How Kodiqa Compares

Every cell below was checked against each vendor's own documentation in September 2026. Where a vendor doesn't publish something, the cell says "Not documented" instead of guessing.

Where Kodiqa stands alone. Multi-model consensus, cross-provider failover, OpenAPI and GraphQL endpoints as callable tools, conversation branching, a per-session spend cap, batch edit review, and RAG over your own codebase. No other agent in this table ships all of them, and most ship none of them.

Where Kodiqa is behind. There is no desktop app and no shareable session links, and the CI bot covers GitHub only. Those are roadmap items, not shipped features.

Install

pip install kodiqa
kodiqa

Requires Python 3.11 or newer. python -m kodiqa works too.

Features

• Claude Code-style UI — ❯ prompt with separator line (prompt_toolkit), arrow-key navigation for all prompts
• 32 tools — file ops, git, search, web, memory, clipboard, multi-edit, undo, diff apply, live task list, background commands, skills, and explore to delegate research to a sub-agent
• 9 API providers — Ollama (local/free), Claude, OpenAI, DeepSeek, Groq, Mistral, Qwen, OpenRouter, Venice (hundreds of models)
• Editor/IDE bridge — kodiqa --serve exposes a local HTTP API (/ask, /diagnostics) for VS Code/Zed/Neovim extensions
• Cross-provider failover — if a provider is down/rate-limited, the turn auto-retries on the next configured provider and continues (/failover)
• TOON output — /toon re-encodes JSON tool results into a compact tabular form (~60% fewer tokens on large arrays)
• Custom commands — drop .kodiqa/commands/<name>.md and run it as /<name> (with $ARGUMENTS/$1 substitution); /commands lists them
• Skills — .kodiqa/skills/<name>/SKILL.md instructions the model loads by itself when a task matches their description; /skills lists them
• MCP server support — connect external tool servers via Model Context Protocol
• Lazy MCP tools — large MCP servers are discovered on demand (mcp_search / mcp_call) instead of injecting every tool schema each turn — ~94% fewer tool-schema tokens (/mcp lazy)
• Auto model discovery — new Claude/Qwen models appear automatically from APIs
• Interactive pickers — /model and /key show numbered menus, navigate with arrows
• Tab autocomplete — slash commands, model names, file paths (prompt_toolkit)
• Compact streaming — hides code output, shows progress instead (toggle with /verbose)
• Stream interrupt — press Esc or Ctrl+C to stop any response instantly
• Stream stall indicator — animated spinner when response pauses (so you know it's still working)
• Thinking display — shows spinner for <think> reasoning blocks, line count summary
• Multi-model consensus — query all models, merge best answers
• 3 permission modes — default (confirm all), relaxed (auto file ops), auto (no confirms)
• Plan mode — AI explores + plans, you approve, then it implements
• Batch edit review — queue edits, accept/reject per file with arrow keys
• Context window management — warns at 70%, auto-compacts at 85%, visual progress bar
• Conversation branching — save/switch between conversation states
• Token tracking — cost per response, session totals, tok/s speed
• Prompt caching — Claude API cache for faster + cheaper responses
• Auto-retry — exponential backoff on API errors (429, 5xx, timeouts)
• Undo / redo / rewind — per-file undo (up to 10 levels) with /redo, plus /rewind to revert ALL file changes from the last turn(s)
• Checkpoints — save/restore conversation state
• Session export — export conversation to markdown
• Git-aware context — auto-detects git repo, includes diff stats
• Project indexing — symbol extraction (def/class/function), cached
• Shell env detection — auto-detects OS, shell, dev tools
• Diff preview — colored diff before every file write/edit
• Parallel tools — read-only operations run concurrently
• Session summary — auto-saves context summary on quit, loaded on next start
• Conversation recovery — auto-saved sessions, resume on crash or with kodiqa -c / --resume
• Workspace boundary — asks permission before accessing files outside working directory
• Smart Ollama lifecycle — starts on launch, stops when switching to cloud, restarts on local switch
• Dynamic model library — scrapes ollama.com/library on every launch (never a baked-in list) with pull counts, download sizes, and whether the model fits your RAM
• Unlimited iterations — no artificial cap, AI keeps working until the task is done
• Live API model routing — auto-discovered models from Claude/Qwen APIs routed to correct provider
• Auto git commit — toggle with /autocommit, auto-commits after AI edits with descriptive message
• .kodiqaignore — per-project exclusion for scans and searches: file names (secrets.txt, .env), globs (creds_*.json), extensions (*.log) and directories (node_modules/)
• Budget limit — /budget 5 sets $5 session limit, warns at 80%, blocks at 100%
• Auto-lint — /lint ruff check --fix runs linter after edits, feeds errors back to AI
• Custom personas — /persona switches AI expertise (security-expert, code-reviewer, teacher, architect, debugger)
• RAG search — /embed indexes codebase, /rag searches with AI-enhanced context
• Test generation — /test <file> auto-generates unit tests
• Git diff review — /review-local AI reviews staged changes
• Interactive debugger — /debug <script> runs, catches errors, debugs with AI
• Diagram generation — /diagram generates Mermaid diagrams via AI
• File watcher — /watch <path> monitors for changes
• Config profiles — /profile save/load manages settings presets
• Multi-file refactoring — /refactor rename/extract across project
• Session history — /history browses and resumes past sessions
• Clipboard patches — /patch applies diffs from clipboard
• Changelog — /changelog shows version history
• Session stats — /stats shows metrics (files, tools, time, cost)
• 1237 tests — pytest test suite, all passing

Arrow-Key UI

All interactive prompts use arrow keys — no typing letters:

  Allow: Write file: ~/project/app.py
    ❯ Yes
      Yes, don't ask again — for this action type
      No

Navigate with ↑↓ arrows or j/k, press Enter to select, or 1/2/3 to jump.

Prompt uses a separator line (like Claude Code):

────────────────────────────────────────
❯ your prompt here

Slash Commands

Permission Modes

Switch with /mode relaxed or /mode auto. Default is default.

Hooks

Run your own command before or after any tool, in ~/.kodiqa/config.json:

"hooks": {
  "pre_run_command": "./scripts/allow-command.sh {command}",
  "post_write_file": "ruff check {path}"
}

Keys are pre_<tool> / post_<tool>; {param} is replaced by that tool parameter, shell-quoted.

• A pre-hook is a gate. The tool runs only if the hook exits 0. A non-zero exit, a timeout (30s) or a hook that cannot start all block it, and the model is told why, including the hook's output.
• A post-hook reports. The action has already happened, so it cannot be blocked; if the hook fails, its output is added to the tool result so the model can fix what it flagged.
• With batch edit review, a file's post-hook runs when you accept the edit and it is written, not when it is queued.
• For a background command, post_run_command runs once the command has started, not when it ends.

Skills

A skill is a set of instructions the model loads on its own when a task calls for it: how this project cuts a release, writes migrations, or formats a changelog entry. Only each skill's name and one-line description sit in the prompt, so a project can carry many of them for a few dozen tokens each. When a task matches a description, the model calls the skill tool and gets the full instructions.

.kodiqa/skills/changelog-entry/SKILL.md      (project; ~/.kodiqa/skills/ for global)
---
description: How this project writes changelog entries. Use whenever asked to
  write or add a changelog or release-notes entry.
---
1. The first line is exactly: `### Entry`
2. One bullet per change, each starting with a past-tense verb.
3. End with the ticket id from templates/ticket.txt.

• The directory name is the skill's name. A project skill wins over a global one with the same name.
• A skill can carry files. The model is told the skill's directory, so templates/ticket.txt above is read from there.
• A broken skill is reported. /skills lists every skill; one with no description, or with unclosed frontmatter, is shown with the reason instead of silently doing nothing. /skills <name> prints one.
• Skill or custom command? A custom command (.kodiqa/commands/) runs when you type it. A skill is picked up by the model when the task matches, even if you never mention it.

Background Commands

A dev server, a file watcher or a long test run no longer blocks the turn — or gets killed at the 120-second command timeout. The model starts it with run_command and background: true, gets a job id at once, and keeps working:

run_command  npm run dev  (background)   →  Started job_1 (pid 48211)
job_output   job_1  until "ready|listening"   →  waits until the server is up (max 60s)
run_command  curl -s localhost:5173/api/health
job_output   job_1   →  only the lines printed since the last read
job_stop     job_1   →  stops npm and everything it started

• Same protections as any command — the confirmation prompt (relaxed mode still asks), the blocklist, /sandbox and pre_run_command hooks all apply.
• Never hangs on its own output — output goes to a log file, so a chatty process can't fill a pipe and freeze; each read returns only new output, capped to the last 20 KB.
• Stops cleanly — each job runs in its own process group, so stopping it stops its children too. Quitting Kodiqa (or a crash, or the end of a headless run) stops every job, so no server is left holding a port.
• /jobs lists what's running; /jobs log <id> shows the recent output without taking it from the model; /jobs stop <id> or /jobs stop all.

Plan Mode

Activate with /plan. The AI will:

1. Explore — read files, search, analyze (no writes allowed)
2. Present plan — show what it intends to do
3. You decide — approve, revise, or reject (arrow keys)
4. Implement — on approval, AI executes the plan

Batch Edit Review

When enabled (default ON, toggle with /accept), file edits are queued and presented for review:

  ? (1/3) app.py — write  +15 -3 lines
    ❯ Accept
      Reject
      Show diff
      Accept all — remaining 3 edits
      Reject all

Navigate with arrow keys, view diffs, accept/reject individually or in bulk.

MCP Server Support

Connect external tool servers via the Model Context Protocol — local or remote:

# Local (stdio) server — a command Kodiqa runs
/mcp add fs npx -y @modelcontextprotocol/server-filesystem ~/projects

# Remote (HTTP) server — a hosted URL, with optional auth
/mcp add linear https://mcp.linear.app/mcp --bearer env:LINEAR_TOKEN
/mcp add api https://example.com/mcp --header "X-Api-Key:abc123"

# Remote with OAuth login (opens your browser)
/mcp add linear https://mcp.linear.app/mcp --oauth
# …or machine-to-machine (no browser)
/mcp add api https://example.com/mcp --oauth-client-id env:CID --oauth-client-secret env:CSEC

# Any REST API via its OpenAPI spec — each operation becomes a tool (no codegen)
/mcp add petstore --spec https://petstore3.swagger.io/api/v3/openapi.json
# Any GraphQL endpoint — each query/mutation becomes a tool
/mcp add gql --graphql https://api.example.com/graphql --bearer env:TOKEN

/mcp list                                # show servers + kind ([stdio]/[http]/[openapi]/[graphql]) + lazy mode
/mcp remove mytools                      # disconnect
/mcp lazy [on|off]                       # toggle lazy tool loading (default: on)

Remote servers use the Streamable HTTP transport. Auth values support env:VAR and file:PATH so tokens aren't typed inline. OAuth (--oauth) handles discovery, dynamic client registration, the PKCE browser login, and automatic token refresh — tokens are cached under ~/.kodiqa/oauth/ and reused across sessions.

MCP tools are automatically available to the AI alongside built-in tools, and work with lazy mode (discovered on demand).

⚡ Lazy MCP tools — save up to 94% of tool-schema tokens

Most agents paste every MCP tool's JSON schema into every request, so a big MCP server quietly taxes every turn. Kodiqa doesn't. When servers are connected, it exposes 3 fixed meta-tools and lets the model discover tools on demand:

• mcp_search — find tools by keyword, ranked by how often you've used them
• mcp_tool_schema — fetch one tool's full schema only when needed
• mcp_call — run a tool by name

It's on by default, fully automatic (the model drives it), and the cost stays flat no matter how many MCP tools you connect. Toggle with /mcp lazy off, or set mcp_lazy: false in settings to always inject every schema.

Model Shortcuts

Local Models (free, unlimited, requires Ollama)

Claude API Models (paid, requires API key)

Qwen API Models (paid, Alibaba Cloud DashScope)

Qwen Coding Plan: If you have a Coding Plan subscription (sk-sp- key), /key qwen auto-detects it and configures the dedicated endpoint. Supports $3/mo Lite and $15/mo Pro tiers.

OpenAI API Models (paid, requires API key)

DeepSeek API Models (paid, requires API key)

Groq API Models (free tier available)

Mistral API Models (paid, requires API key)

New models are auto-discovered from the APIs — they appear in /model and /models automatically.

You can also use full model names: /model qwen3:14b or /model claude-opus-4-6

Editor / IDE bridge

Run Kodiqa as a small local HTTP server that your editor (VS Code, Zed, Neovim, …) can call:

kodiqa --serve            # prints the URL + an auth token
# or, inside a session:  /serve

It binds to 127.0.0.1 only and requires the printed bearer token. Set a stable token (handy for editor config) with KODIQA_BRIDGE_TOKEN=…, and a fixed port with --port. Protocol:

curl -s localhost:PORT/ask -H "Authorization: Bearer TOKEN" \
  -d '{"prompt":"explain this","context":"def f(): return 1"}'

/ask is a safe, non-streaming Q&A call — ideal for "ask Kodiqa about the selection." A minimal reference client is in examples/bridge_client.py; editor extensions are thin clients over this API.

GitHub bot

Mention /kodiqa or /kq in an issue or pull-request comment and Kodiqa does the work in your own Actions runner, replies in the thread, and opens a pull request when it changed something.

/kq the parser drops the last token when the input ends in a comma — fix it

Copy examples/workflows/kodiqa.yml to .github/workflows/kodiqa.yml, add your provider key under Settings → Secrets and variables → Actions, and that is the whole setup:

- uses: Kodiqa-Solutions/Kodiqa-agent/github@v3.34.0
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  with:
    model: claude-sonnet-4-6

Currently internal. The source repository is private, and GitHub only lets a private repository's action be used inside its own organization. Until it is public, this uses: line resolves for Kodiqa-Solutions repositories only.

Any provider works — set DEEPSEEK_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY and so on, and name a model that provider serves. Keys are read from the environment, so nothing is written to disk in the runner.

Only maintainers can command it

A workflow that runs an agent hands your API key and your runner to whoever can make the job start. Kodiqa only acts on comments from an OWNER, MEMBER or COLLABORATOR — GitHub decides that, not the commenter. A comment from anyone else is logged and ignored before any model call, so a drive-by comment on a public repository costs nothing.

Set require-trusted: false to lift that, and only on a private repository.

What else it can do

A review job only needs contents: read and pull-requests: write; a job that should open PRs needs contents: write too. Grant the smaller set where you can — a job that cannot write cannot be talked into writing.

Sub-agents

/agent hands a question to a research sub-agent that runs its own tool loop in the background — reading files, grepping, listing directories — and reports back, while you keep working:

❯ /agent where is the retry logic for provider requests, and what does it retry on?
● Spawned agent_1: where is the retry logic... (read-only; /agents to check)

❯ /agents
  ● agent_1 done — where is the retry logic...
  ╭─ agent_1 ─────────────────────────────────────────────────────╮
  │ _retry_api_call in kodiqa/agent.py retries on 429 and 5xx... │

It has its own context: the research never lands in your conversation, only the report does. It is read-only — read_file, grep, glob, tree, list_dir, git_status, git_diff, read_pdf, read_image, web_search, web_fetch, memory_search — so it never needs to ask you anything and can safely run in the background. Paths outside your project are refused rather than prompted for.

/team <task> splits a task into up to four subtasks, runs a sub-agent on each in parallel, and merges what they found.

The model can delegate by itself

You do not have to type /agent. The explore tool lets the model hand an open-ended question to a sub-agent on its own — "where is retry handled", "which callers pass a timeout" — and continue with only the report. Several explore calls in one turn run in parallel. The investigation never lands in your conversation, so a search that needed twenty reads costs your context one reply.

Sub-agent spending is booked against the session, so /budget covers it, and a sub-agent stops before its next request once the budget is spent.

Works with Claude, every OpenAI-compatible provider, and local Ollama models that support tool calling.

Your own sub-agents

Define a specialised sub-agent in .kodiqa/agents/<name>.md (or ~/.kodiqa/agents/ for every project):

---
description: Reviews code for real bugs. Use whenever asked to review or check code.
tools: read_file, grep, glob, git_diff      # optional — narrows the default read-only set
model: deepseek-chat                        # optional — an alias or full id; default: your model
max_steps: 20                               # optional — 1 to 50, default 15
---
You are a strict code reviewer. For each real defect give file:line, what goes
wrong, and one input that triggers it. Do not report style issues.

• The model picks it by itself. It sees each agent's name and description and delegates with explore and agent: "reviewer" when a task matches. You can call one directly with /agent @reviewer <task>.
• Its own model. A cheap, fast model can do the searching while your main model does the thinking. Its spend is booked at that model's price and counts toward /budget.
• Still read-only. Sub-agents run in the background and never prompt, so a definition that asks for write_file or run_command is not loaded. /agents lists every definition and says why a broken one was refused.

Scripting and CI

Run a task without the UI and get the answer back:

kodiqa --headless "add error handling to the retry loop in client.py"

With --format json, stdout carries one object and nothing else — every panel, spinner and diff moves to stderr — so it pipes straight into jq:

kodiqa --headless "audit the dependencies" --format json | jq

{
  "ok": true,
  "task": "audit the dependencies",
  "model": "claude-sonnet-4-6",
  "result": "Two packages are a major version behind …",
  "error": "",
  "files_changed": ["requirements.txt"],
  "tools_used": {"read_file": 6, "edit_file": 1, "run_command": 2},
  "counts": {"messages": 1, "files_read": 6, "files_edited": 1, "commands_run": 2, "searches": 0},
  "tokens": {"input": 84210, "output": 6120, "cache_read": 71000, "cache_creation": 0},
  "cost": 0.3271,
  "elapsed_s": 128.4
}

Which makes the usual CI things one-liners:

# fail the job if a task costs more than a dollar
COST=$(kodiqa --headless "$TASK" --format json | jq '.cost')
awk "BEGIN{exit !($COST > 1.0)}" && echo "too expensive" && exit 1

# did it actually change anything?
kodiqa --headless "$TASK" --format json | jq -e '.files_changed | length > 0'

Exit codes. 0 when the run produced an answer or changed a file, 1 when it raised — and 1 when it finished having produced nothing at all. That last case is what an unreachable provider or an uninstalled local model looks like: Kodiqa prints a hint and returns normally, which would otherwise report success for a run that never happened.

--result FILE writes just the final answer, and --output FILE the full transcript, if a file suits you better than stdout.

Compact Streaming Mode

By default, Kodiqa hides code blocks during streaming and shows progress instead:

Kodiqa  I'll create the project structure...

  ⠋ Writing code (javascript)... 45 lines, 1,890 chars
  ╰─ code block: javascript 45 lines, 1,890 chars

Now the package.json:

  ⠋ Writing code (json)... 12 lines, 340 chars
  ╰─ code block: json 12 lines, 340 chars

  1,204 in / 847 out | 42.3 tok/s | ($0.0061 / session: $0.0183)

Use /verbose to toggle full output (see all code as it streams).

API Setup

Use /key to add API keys interactively (shows all 8 providers), or specify directly:

Then switch: /model claude, /model gpt, /model deepseek, /model llama, /model mistral, /model qwen3.5

Keys from the environment

Every provider also reads its key from the environment, which takes precedence over settings.json. This is what makes CI, devcontainers and direnv work without a settings file — and it lets you override a stored key for one shell.

If one of those names is already taken by something else, KODIQA_<PROVIDER>_API_KEY wins over it. A key found in the environment is never written to settings.json — the environment owns that value. /help marks such providers as connected, from env.

What You Can Ask

File Operations

read the file ~/.zshrc
create a file called hello.py with a hello world program
edit main.py and change the function name from foo to bar
move config.json to config.backup.json
delete the temp file at ~/scratch.txt

Multi-Edit & Undo

rename all occurrences of "oldName" to "newName" in utils.py
undo the last edit to main.py

Search

find all .py files in ~/projects
search for "TODO" in my project

Commands & Git

run npm install
show me the git status
commit these changes with message "fix login bug"

Web Search

search the web for kotlin coroutines tutorial
fetch the content from https://some-docs-page.com

Memory

remember that I prefer Kotlin for Android development
what do you remember about my preferences?

Images & PDFs

look at this screenshot ~/Desktop/screenshot.png
read the PDF ~/Documents/report.pdf

Clipboard

paste what's on my clipboard
copy this code to clipboard

Project Analysis

/scan ~/myapp
now explain what this project does
find any bugs in this code

Safety

• Auto-approved: reading files, listing dirs, searching, web, memory, clipboard read, undo
• Asks permission: writing/editing files, running commands, git commits, delete, move, clipboard write, patches
• Workspace boundary: asks before accessing files outside current working directory (Allow once / Allow directory / Deny)
• Blocked: rm -rf /, sudo rm, mkfs, dd, fork bombs, etc.
• Permission modes: /mode default (confirm all) → /mode relaxed (auto file ops) → /mode auto (no confirms)

32 Tools

Files

~/LLMS/kodiqa/
  kodiqa/            # the package (everything imports as kodiqa.<module>)
    agent.py         # Main agent (7558 lines)
    actions.py       # Action handlers (1287 lines)
    tools.py         # Tool schemas (497 lines)
    config.py        # Config, themes, provider registry (1046 lines)
    web.py           # Web search + page fetch (241 lines)
    memory.py        # SQLite persistent memory (94 lines)
    mcp.py           # MCP client (444 lines)
    templates.py     # 5 project templates (61 lines)
    lsp.py           # LSP client (272 lines)
    embeddings.py    # RAG vector store (92 lines)
    repomap.py       # Tree-sitter/regex repo map (163 lines)
  github/            # the GitHub action (not part of the pip package)
  examples/          # bridge client + workflow templates
  bin/kodiqa         # Global install script
  tests/             # 1237 tests (pytest)
  pyproject.toml     # Package config (pip install .)
  requirements.txt   # Dependencies

~/.kodiqa/
  config.json        # User-editable config (overrides defaults)
  settings.json      # API keys, default model
  memory.db          # Persistent memories
  session.json       # Auto-saved conversation
  input_history      # prompt_toolkit FileHistory
  error.log          # Error log (capped 1MB)
  KODIQA.md          # Global context (always in system prompt)
  projects/          # Per-project context files
  checkpoints/       # Conversation checkpoints
  exports/           # Exported session markdown files

Tips

• All prompts use arrow keys — no typing letters, just navigate and press Enter
• Default is compact mode — code hidden during streaming, progress shown instead
• Use /verbose when you want to see code as it streams
• Use /mode relaxed to skip file edit confirmations
• Use /plan for complex tasks — review the plan before implementation
• Use /accept to toggle batch edit review on/off
• Use /branch save before experimenting — switch back if it goes wrong
• Use /mcp add to connect external tool servers
• Use /checkpoint before risky operations, /restore to roll back
• Use /export to save a conversation for later reference
• Use /tokens to monitor API costs and context usage
• Use /model with no arg for interactive picker
• Use /key with no arg to choose provider
• Tab complete works for commands, models, and file paths
• New API models appear automatically — no code updates needed
• Memories persist forever across sessions
• Arrow keys work: up/down for history, left/right to edit
• Sessions auto-save — restart if anything goes wrong
• Session summary auto-saved on quit — next start has full context
• Type quit or exit (no slash needed) to exit
• Ollama starts/stops automatically — stops on cloud switch, restarts on local switch

Testing

pytest -v          # 1237 tests, all passing

Requirements

• Python 3.11+
• Ollama installed (/Applications/Ollama.app on macOS) — or just use API models
• Models pulled automatically on first run, or ollama pull qwen3-coder
• (Optional) Claude API key for Claude models
• (Optional) DashScope API key for Qwen API models

License

Kodiqa is open source under the AGPL-3.0 License.

For commercial use without AGPL obligations, see Commercial License or contact eniz@kodiqa.com.