Connect your own coding agent to Ithura

Hand a task to a coding agent and have it work the task like anyone else: pick up what was delegated to it, report what it is doing, open a pull request, and come back when a reviewer asks for changes. For what the states mean and how a pull request drives them, read tasks that follow their pull request.

There are two ways in:

  • Run ithura-agent, the official runner. You point it at a repository and a coding CLI you already use. Most people want this.
  • Build your own, against the run API. Everything the official runner does is a public endpoint.

Where this runs, and what Ithura can see

You run the agent on your own machine or server. It holds three secrets, and all three stay yours:

  • an Ithura API token, so it can read its tasks and report back
  • credentials for whichever AI provider you use
  • push access to your own repository

Ithura never sees your provider credentials, never pays for your AI, and never runs your code. What it stores is what the agent reports: run events, a summary, a question if it asks one, and token counts with an optional cost.

You are responsible for following your provider's terms for the way you run it, including unattended use on a subscription. Check them before you switch this on.

Before you start

Three preconditions. The first two are not guessable from the endpoints, and getting either wrong fails later than you would like:

  1. The Pro plan or higher. Every run endpoint is gated on it.
  2. The API token must be bound to an agent. In Settings, Agents, register an agent and pick one of your API tokens. Registering needs workspace admin.
  3. The task must be delegated to that same agent. Otherwise starting a run returns 403 This task is not delegated to this agent. The same message covers a task with no delegate at all, so check both.

Throughout, {slug} is your workspace slug. The API is at the root of your API host with no /api prefix.

Option A: run ithura-agent

One program, one config file. It polls for work, runs your coding CLI in a git worktree, pushes a branch, opens a pull request, and reports every step back to the task.

Install

# from go-app/ in a checkout
go build -ldflags "-X main.version=$(git describe --tags --always --dirty)" \
  -o ithura-agent ./cmd/ithura-agent

make agent-dist builds static binaries for linux and macOS on amd64 and arm64. Either way the version is stamped in, so ithura-agent version tells you what you are running.

Configure and check

Copy ithura-agent.example.yaml, edit it, then:

export ITHURA_AGENT_TOKEN=...          # never put the token in the file
ithura-agent check -config ithura-agent.yaml
ithura-agent run   -config ithura-agent.yaml    # loop
ithura-agent once  -config ithura-agent.yaml    # one pass, then exit

Run check first. It tests the config, the Ithura token, the git repo and base branch, the push method, and that the provider binary is on your PATH, and exits non-zero if any of them fail. It is much cheaper than discovering a bad base branch halfway through a run. Unknown keys in the config are an error, so typos get caught rather than silently ignored.

Choosing a provider

AdapterStatus
claude-codeParser checked against real recorded output
commandAny CLI. Prompt on stdin, each output line becomes a step. No token counts
codexExperimental, not verified against a real CLI
geminiExperimental, not verified against a real CLI

codex and gemini refuse to start unless you set provider.experimental: true, and the runner warns at startup. That gate is deliberate: they have only been exercised against synthetic fixtures.

How you authenticate decides the cost label

The agent reports how it was billed, and Ithura labels the run accordingly:

How you authenticate claude-codeReported asShown on the task
An API key, or Bedrock or Vertexapi"API cost"
A long-lived subscription login tokensubscription"Plan usage (estimate)"
An interactive login already on the machineunknown"Cost"

A subscription figure is an estimate at API prices, not a bill. It is still worth reporting, because it compares runs against each other, but do not read it as an invoice.

Provider credentials are passed to the provider process only if they are on a fixed list for that adapter or named in provider.env_allow. The Ithura token and your GitHub credentials are never passed to the provider.

GitHub

Pick one:

  • push_method: git uses whatever the machine already has, an SSH key or a credential helper. To also open pull requests, set repo.github and point repo.github_token_env at an env var holding a token with pull request write access. Without it the agent pushes the branch and reports the branch name.
  • push_method: github-app uses a GitHub App with Contents read and write, Pull requests read and write, and Metadata read, installed on that repo only. Keep the private key at mode 600. Each push gets a one hour installation token, and pull requests are opened by the app, so a person reviews them.

The task ref goes at the start of the pull request title. That is what links it to the task.

What stops it doing something stupid

Worth reading before you leave it running:

  • Branch guard. A push is refused unless the branch starts with the task ref. The base branch, main and master are always refused. Pushes never use force.
  • During a run the repo's push URL is set to a dead value and the provider is told not to push. The agent pushes afterwards, itself.
  • Blocked commands for claude-code by default: git push, git remote, git config, ssh, scp, curl, wget, gh, kubectl, make deploy.
  • Limits: three runs per UTC day and forty-five minutes per run by default. A run past its time is killed along with its children and reported as failed.
  • It never merges and never deploys.

Use a dedicated clone for repo.path, on a machine that holds only what the agent needs.

Quality gates

Three optional settings help the agent do its work well. All are off until you set them.

  • Checks before the push (verify). You list commands, and for each one the files that make it relevant. When the agent finishes with commits, the runner works out which files changed and runs the checks that match, in the worktree. Each check shows on the task timeline as passed or failed, with the end of the output when it failed. If one fails, the agent gets the output and a limited number of rounds (max_fix_rounds) to fix it, then the checks run again. If a check still fails, nothing is pushed and the run is marked failed with the name of the check. When all pass, the pull request lists what was run.
  • A second pair of eyes (review). After the checks pass, a separate session with read-only tools looks at the diff and lists problems with a severity, file and line. High and medium findings go back to the agent to fix, and the checks run again. Every finding is listed on the pull request under "Reviewer notes". The cost of the review is added to the run.
  • Shared memory (provider.memory_dir, claude-code only). Points every run at one memory folder, so what the agent learns about your repo carries over from task to task.

provider.model picks the model for claude-code and is used for the main run, the fix rounds and the review. The full keys are in the ithura-agent README and the example config.

Option B: build your own against the run API

Four endpoints. Your token needs issues:read for the first and issues:write for the rest.

Find the work

GET /v1/workspaces/{slug}/agent/work/

Returns {"agent": {...}, "work": [...]}. Each item carries the task, its last 30 comments, a branch_hint, any pr_url, and a reason telling you why it is in the list:

ReasonMeaning
newDelegated and not yet worked
feedbackA reviewer requested changes on the pull request
answerSomebody answered the question you asked
inputSomebody sent the agent guidance

Handle all four. A runner that handles only new and feedback will ask a question and then never come back to it, which looks exactly like the agent having died.

Start a run

POST /v1/workspaces/{slug}/agent-runs/
{ "task": "PAR-123", "provider": "your-cli", "kind": "new", "billing": "api" }

Only task and provider are required. kind defaults to new and billing to unknown. task takes a uuid or a ref like PAR-123.

  • kind: new, rework, answer, input or manual
  • billing: api, subscription or unknown
  • provider is at most 40 bytes, model at most 120, session_url must be https

Returns 201 with the run id. Starting a run moves an idle task to working. A task already working just gets the run attached. A task in waiting_on_human, in_review or done returns 409, which is worth handling rather than retrying.

Report progress

POST /v1/workspaces/{slug}/agent-runs/{runID}/events/
{ "events": [ { "type": "step", "text": "Reading the failing test" } ] }

type is one of step, tool, test, commit, message, question, pr or error.

At most 50 events per call and 500 per run. text over 8000 characters is cut and ends with ... (cut at 8000 characters). data over 256 KiB is cut and gets "truncated": true, and an event whose text was cut also gets "truncated": true in its data. Returns 202 {"accepted": n, "dropped": n}. Note dropped: events past the per-run cap are discarded silently rather than rejected, so watch that number instead of assuming everything landed. A run summary or question over 32000 characters is cut the same way.

Finish

POST /v1/workspaces/{slug}/agent-runs/{runID}/finish/
{ "status": "succeeded", "summary": "Fixed the overflow", "usage": { "model": "...", "prompt_tokens": 1, "completion_tokens": 2, "cost_usd": 0.4 } }

The field is status, and it is one of:

StatusWhat happens to the task
succeededNot moved by itself. It goes to in_review only if the task is still working for this agent and has an open, non-draft pull request. With newer unaddressed feedback it stays working and comes back as feedback
askedMoves to waiting_on_human. question is required
failedRecorded. The task is left alone, and the summary is kept as the error
no_changeRecorded. The task is left alone

Retrying finish with the same status is idempotent and writes usage once, so a retry after a network failure is safe. A different status on an ended run gives 409.

Cost goes in the usage block here. There is no cost field on start.

How the conversation works

The task is the conversation. Not your agent's memory, not a log on your server: the task's title, description, comments, feedback, and its branch and pull request. Treat every run as a fresh session, because sooner or later one will be, after a restart or on another machine.

So on every run, read the task, its comments and its feedback, and continue on the branch you already made. Anything the agent knows that is not written back is lost when the process exits, and invisible to the people working alongside it.

Agent to people

  • Run events appear on the task timeline, with the cost label and the pull request link.
  • A question (finish with asked) puts the task in waiting_on_human, shows the question on the task and in Needs you on Home, and notifies the assignees and whoever delegated it. Then stop and wait. An agent that asks and guesses anyway has done something worse than either.
  • Runs also appear as a thread in the project's chat channel.

People to agent

  1. Answering the question, on the task or by replying in the chat thread. The answer is saved as a comment from that person, the question is cleared, and the task returns to working. The agent cannot answer itself.
  2. Requesting changes on the pull request, which sends it back with the review text as feedback. GitHub only.
  3. Guidance at any time, as an ordinary comment, a non-answer reply in the thread, or @Agent in any channel with a task ref.

Comments from people outside your workspace never reach the agent. The bot thanks them once and stops there.

Optional: let the agent read the decisions already made

Workspace decisions and team memory are on the same API. An agent that reads them first will follow conventions the team has already settled rather than relitigating them in a pull request.

Error reference

Code and messageWhat it usually means
402 Agents require the Pro planThe workspace is below Pro
403 This token is not bound to an agent in this workspaceRegister the agent in Settings, Agents and pick this token
403 This task is not delegated to this agentNot delegated at all, or delegated to a different agent
403 token missing required scopeThe body names it. issues:write for runs, issues:read for work
403 token is pinned to a different workspaceRight token, wrong workspace
409 Cannot start a run while delegation is XThe task is waiting on a person, in review, or done
409 Run already ended as XFinishing a run twice with different statuses
400 question is required when status is askedAsking without a question

Older endpoints

Agents built before the run API used POST /v1/.../issues/{iid}/delegation/state/ to report state and POST /v1/.../agent-usage/ to report cost. Both still work and neither is deprecated. They do less: no run record, so nothing appears on the run timeline. New agents should use the run API, which is what the official runner uses.