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:
- The Pro plan or higher. Every run endpoint is gated on it.
- 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.
- 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
| Adapter | Status |
|---|---|
claude-code | Parser checked against real recorded output |
command | Any CLI. Prompt on stdin, each output line becomes a step. No token counts |
codex | Experimental, not verified against a real CLI |
gemini | Experimental, 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-code | Reported as | Shown on the task |
|---|---|---|
| An API key, or Bedrock or Vertex | api | "API cost" |
| A long-lived subscription login token | subscription | "Plan usage (estimate)" |
| An interactive login already on the machine | unknown | "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: gituses whatever the machine already has, an SSH key or a credential helper. To also open pull requests, setrepo.githuband pointrepo.github_token_envat 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-appuses 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,
mainandmasterare 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-codeby 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:
| Reason | Meaning |
|---|---|
new | Delegated and not yet worked |
feedback | A reviewer requested changes on the pull request |
answer | Somebody answered the question you asked |
input | Somebody 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,inputormanualbilling:api,subscriptionorunknownprovideris at most 40 bytes,modelat most 120,session_urlmust 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:
| Status | What happens to the task |
|---|---|
succeeded | Not 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 |
asked | Moves to waiting_on_human. question is required |
failed | Recorded. The task is left alone, and the summary is kept as the error |
no_change | Recorded. 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 (
finishwithasked) puts the task inwaiting_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
- 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. - Requesting changes on the pull request, which sends it back with the review text as feedback. GitHub only.
- Guidance at any time, as an ordinary comment, a non-answer reply in the thread, or
@Agentin 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 message | What it usually means |
|---|---|
402 Agents require the Pro plan | The workspace is below Pro |
403 This token is not bound to an agent in this workspace | Register the agent in Settings, Agents and pick this token |
403 This task is not delegated to this agent | Not delegated at all, or delegated to a different agent |
403 token missing required scope | The body names it. issues:write for runs, issues:read for work |
403 token is pinned to a different workspace | Right token, wrong workspace |
409 Cannot start a run while delegation is X | The task is waiting on a person, in review, or done |
409 Run already ended as X | Finishing a run twice with different statuses |
400 question is required when status is asked | Asking 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.