agentklar. by kaltstart.co

What it is & how to use it

Agentklar, in plain terms.

It's a local command-line tool that gives every coding task a lifecycle your AI agent has to follow — you define what “done” means, the agent does the work and proves it with your tests, and only you approve.

The idea

Think of it as an issue tracker + a test gate + an approval step — all local, that your agent drives but can't shortcut.

01

You run one binary

No servers to babysit, no Docker, no sudo. Point your agent (Codex, OpenCode, Gemini CLI) at it and keep your own model.

02

Every task has a lifecycle

Draft → Ready → In Progress → checks → your approval → Done. The agent moves cards forward, but can't skip the checks or approve itself.

03

Nothing is “done” on trust

Agentklar runs your actual test commands and keeps the receipts. Only a human, from their own account, marks a task finished.

The board Agentklar sets up for you (on Vikunja)

Cards move left to right. Review + Auto QA are automatic gates · Your approval is the only human-only step · Done is final. Scroll the board sideways →

The whole flow

Every step is one command. Here's exactly what you type.

This is the entire loop, start to finish. Copy any block and run it.

1Set up your project (once)you
$ agentklar init proposed .agentklar/quality.toml — the commands Agentklar will run workspace ready · repository: ~/code/shop
2Describe the task & what “done” meansyou
$ agentklar task new AK-142 Add pagination to /orders \ --criteria "returns 20 per page;?page= works;tests pass" \ --verify "go test ./..." created AK-142 [standard] in Draft with 3 criteria (board #142)
3Mark it readyyou
$ agentklar task ready AK-142 AK-142 is Ready # a task with no criteria can't become ready
4Your agent claims it and does the workagent
# point your agent's MCP client at: agentklar mcp # it claims the task, writes code, and submits — over MCP → claim_task AK-142 ok · fencing #7 → submit_for_review ok · head 9c1f2a
5Run the gate — your checks, kept as proofyou
$ agentklar gate AK-142 ▸ go build ./... ok ▸ go test ./... ok ✓ completion review + auto QA passed evidence stored: 2 machine-attested · state → user_approval
6You approve — the agent can'tyou
→ (agent tries) approve_task ✗ not agent-callable $ agentklar approve AK-142 # you, from your own account ✓ AK-142 done · signed off by you

Command reference

Every command, and what it does.

The full surface. Run agentklar <command> --help for flags.

Set up

agentklar initCreate a workspace for the current repo and propose the checks to run.
agentklar doctorShow health: declared checks, missing commands, task counts.
agentklar tracker connect --url --svc-user --humanConnect a live Vikunja board; approvals happen as a comment from your account.

Shape work

agentklar task new <id> <title> --criteria --verify --laneCreate a task with acceptance criteria and how to verify it.
agentklar task ready <id>Move a task to Ready (blocked until it has criteria + a verify method).
agentklar task listList every task with its lane and current state.
agentklar task show <id>Show one task with its acceptance criteria and evidence.

Run & connect the agent

agentklar mcpStart the agent-facing server. Point Codex / OpenCode / Gemini CLI at this.
agentklar gate <id>Run the checks for the submitted commit and store machine-attested evidence.
agentklar reconcilePull board comments and apply a valid human approval to finish a task.

Finish (human-only)

agentklar approve <id>Approve a task that passed the gate. No agent can call this.
agentklar reject <id> <reason>Send it back to Changes Requested with a reason.

What plugs in

Agentklar is the hub. You bring the pieces.

It doesn't replace your tools — it wires the ones you already use into one workflow.

Codex
Gemini CLI
OpenCode
↓  MCP  (agentklar mcp)
Agentklarthe control plane on your machine
↓
Vikunja boardagentklar tracker connect
Your test commands.agentklar/quality.toml
Git worktreesisolation per task
Review providersroadmap
mdBook docsroadmap
Community packsroadmap

Honest status

What works today.

An early slice. The core loop is real and tested end to end — including a live board with human approval. The rest is on the roadmap.

Working now

  • Tasks, lifecycle & the Kanban board
  • Definition of Ready enforcement
  • The gate: your checks + Slop Guard
  • Machine-attested evidence
  • Human-only approval (CLI + Vikunja)
  • Agent connection over MCP

On the roadmap

  • Cross-provider independent review
  • Context index & focused work packets
  • Onboarding for existing repos
  • Docs catalogue (mdBook)
  • Community pack library
  • Signed release & installer
Get started → View on GitHub