Setup & Usage

From install to a task moving across the board.

Agentklar is one local binary. Bring your own coding agent and (optionally) your own Vikunja board. Here's the whole path.

1 · Install

Get the binary.

From a release (recommended)

Download your OS/arch archive from the Releases page, verify against checksums.txt, and put it on your PATH.

# example: macOS arm64
tar xzf agentklar_*_darwin_arm64.tar.gz
install -m 0755 agentklar ~/.local/bin/agentklar
agentklar version

From source (Go 1.25+)

git clone https://github.com/kaltstart-co/agentklar
cd agentklar && go build -o ~/.local/bin/agentklar ./cmd/agentklar

2 · Connect your agent (MCP)

Point your agent at Agentklar.

Print the config for your client and paste it in — the absolute binary path is filled in for you.

agentklar mcp install                 # Codex, OpenCode, and generic
agentklar mcp install --client codex  # just one

Your agent can then call list_ready_tasks, claim_task, submit_for_review — but not approve or finish a task. Completion stays human-only.

3 · Set up a board

The board is your UI (Vikunja).

Agentklar drives Vikunja — it doesn't build its own web app. You can skip this and run tracker-less, but the board is where the workflow is easiest to see.

You already run Vikunja

Use a separate service account for the bot (so it can never approve its own work), and name the account that approves. connect creates the project, shares it, and creates the eight workflow columns.

agentklar tracker connect \
  --url https://vikunja.example.com/api/v1 \
  --svc-user agentklar-bot --svc-pass '******' \
  --human you

Prefer an API token? Use --svc-token <token> instead of user/pass.

You don't have Vikunja yet

One container is enough for one person. Then register your user and a second agentklar-bot user, and run the connect command above with --url http://localhost:3456/api/v1.

docker run -p 3456:3456 \
  -e VIKUNJA_SERVICE_PUBLICURL=http://localhost:3456/ \
  vikunja/vikunja:latest

4 · Run a task

End to end.

agentklar init                        # once per repo

# 1. you shape the task — no criteria, no "ready"
agentklar task new AK-1 Fix the parser \
  --criteria "handles empty input;tests pass" --verify "go test ./..."
agentklar task ready AK-1

# 2. your agent claims and does the work over MCP, then submits

agentklar gate AK-1                    # your checks → machine-attested evidence
agentklar approve AK-1                 # you finish it — the agent can't

Cards move as tasks move. To force the board to match the current state, run agentklar tracker sync. The trusted approval (vs. the dev shortcut) is a approve <nonce> comment on the card from your own account, then agentklar reconcile.

5 · Every command

Reference.

agentklar initCreate a workspace for the current repo, propose the checks to run

task new / ready / list / showShape and inspect tasks

agentklar mcpRun the agent-facing MCP server (your agent launches this)

agentklar mcp install [--client]Print MCP config to connect your agent

agentklar gate <id>Run the checks, store machine-attested evidence

agentklar tracker connect …Connect a Vikunja board (new or existing)

agentklar tracker syncPlace every task's card in its state column

agentklar reconcileApply a human approval posted on the board

agentklar approve / reject <id>Finish a task (human-only)

agentklar doctorHealth: declared checks, missing commands, task counts

agentklar versionVersion, commit, build date

Scoping: Agentklar resolves your workspace from the current git repo, so task list shows only that repo's tasks — one repo, one board.