kodiqa 3.25.0

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

84 slash commands • 28 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 CI bot, no desktop app, and no shareable session links. Those are roadmap items, not shipped features.

Install

pip install kodiqa
kodiqa

Or from source:

git clone https://github.com/Kodiqa-Solutions/Kodiqa-agent.git
cd Kodiqa-agent
pip install .
kodiqa

Features

• Claude Code-style UI — ❯ prompt with separator line (prompt_toolkit), arrow-key navigation for all prompts
• 28 tools — file ops, git, search, web, memory, clipboard, multi-edit, undo, diff apply, live task list
• 8 API providers — Ollama (local/free), Claude, OpenAI, DeepSeek, Groq, Mistral, Qwen, OpenRouter (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
• 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 file exclusion (like .gitignore for scans/searches)
• 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)
• 925 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.

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.25.0
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  with:
    model: claude-sonnet-4-6

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.

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

28 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/             # 925 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          # 925 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.