trakkar-agent

Local runner for Trakkar's AI task delegation. It watches for tasks you delegate to an agent in Trakkar, runs Claude Code on your own repo, opens a pull request, and streams its progress back into the task.

Trakkar never sees your code or your credentials — everything runs on the machine where you start this.

How it works

1. You delegate a task to an agent in Trakkar.
2. This runner (running inside your repo) claims it, reads the task, and runs Claude Code.
3. Claude implements the change; the runner opens a PR and reports the link + progress back to Trakkar.

Prerequisites

• Node.js ≥ 18
• A coding-agent CLI, depending on --provider:
  • claude_code (default) — Claude Code logged in with your Pro/Max plan (run claude once interactively, or set CLAUDE_CODE_OAUTH_TOKEN). Uses your subscription — no ANTHROPIC_API_KEY needed, no per-token cost. (From 2026-06-15, headless usage draws from your plan's monthly Agent SDK credit, so it is not unlimited.)
  • cursor — cursor-agent installed, with CURSOR_API_KEY set. Cursor's headless mode bills through its API (not a flat subscription).
• GitHub CLI (gh) authenticated (or push credentials configured) so it can open PRs.

Setup

In Trakkar: Settings → AI Agents → Add Agent (Claude Code). Copy the token it shows you (shown once).

Then, inside the repo you want the agent to work on:

export TRAKKAR_TOKEN=trk_agent_…
npx trakkar-agent@latest

It watches for delegated tasks and works on them in parallel (up to --max-concurrency, default 6).

Options

--token <t>            Agent token (or env TRAKKAR_TOKEN)            [required]
--api-url <u>          Trakkar API base (or env TRAKKAR_API_URL)     [default https://api.trakkar.in]
--provider <p>         claude_code | cursor                          [default claude_code]
--interval <s>         Poll interval in seconds                      [default 15]
--timeout <s>          Max seconds for the verify command (agent runs are uncapped)  [default 1800]
--max-concurrency <n>  Override the agent's configured parallel-task limit  [default: the agent's setting, or 6]
--once                 Poll once and exit
--dry-run              Claim + read the task only (no agent, no PR) — useful to test the connection
-h, --help             Show help

Notes

• One instance now works multiple delegated tasks in parallel — up to --max-concurrency (default 6). Each task runs in its own isolated git worktree under .trakkar-worktrees/ (kept out of your git status via .git/info/exclude) branched off a fresh origin/<default-branch>, so concurrent tasks never touch each other's files. New delegations start immediately while others are still running. Concurrency is configured per agent in Trakkar (Settings → AI Agents); the runner reads it at startup. Pass --max-concurrency to override it for a single run.
• Higher concurrency means proportionally more load and cost: N parallel Claude Code runs spend your subscription's monthly Agent SDK credit ~N× faster and use ~N× CPU/RAM if a verify_command build runs. Tune with --max-concurrency.
• If a verify_command is set, the runner symlinks your repo's node_modules into each worktree so the build can run.
• The runner is an always-on worker: an agent run is never killed by a timer — it runs until it finishes or you click Stop in Trakkar (or close the runner). A task's worktree is kept until a pull request is opened. If a run stops, fails, or you Stop it, the workspace is retained, so you can just reply in the task chat to continue ("continue from where you stopped", "do X instead") and the agent resumes in the same workspace. Worktrees for unfinished tasks accumulate under .trakkar-worktrees/ until they reach a PR; delete that folder if you abandon work.
• The agent runs Claude with --dangerously-skip-permissions so it can edit files unattended. Only run it in repos you trust it to modify, and review every PR before merging — Trakkar never auto-merges.