Working with a terminal agent

A coding agent in your own terminal, such as Claude Code, can read everything Pitwall shows you through the pitwall command: why a gate failed, which skills a step loaded, what a job did event by event. With your permission it can also file a ticket, start a run and answer its question, to try a change it just made. pitwall CLI lists every command.

Give it a token

1. Install the command on the machine where the agent runs:

   curl -fsSL <core>/api/cli/install.sh | sh -s -- <core>

2. Open Your settings → API tokens, click Create token, and name it after where it will be used, such as “Claude on my laptop”. The token is shown once.

3. Store it in your secrets manager, not in a file of the project, and have the agent run pitwall with it in the environment of that one command, beside PITWALL_URL:

   export PITWALL_URL=https://pitwall.example.com
   <your secrets manager> run -- pitwall whoami

   whoami names you and says "access": "read_only".

Reading is the default

A new token only reads, and that is what most of the work needs. Ask the agent things such as:

• “Which skills did each step of TLY-14 load, and why did each gate pass?” It reads pitwall ticket TLY-14 --trace.
• “What went wrong in implement’s second attempt?” It reads the attempt’s job with pitwall job TLY <job> --events.
• “What happened in milestone 5’s run?” It reads pitwall milestone TLY 5 and the run’s trace.

The answers come from the same data the ticket’s page shows, with nothing to screenshot.

Let it act for a while

When the agent should file a ticket or drive a run, say to try a change it just made, its action is refused first:

pitwall: This token reads only. Allow writes in Your settings → API tokens.

It tells you, and nothing is sent. In Your settings → API tokens, click Allow writes on the token and pick 1 hour, 4 hours or until the end of the day. Writes end on their own at that time; Revoke writes now ends them sooner. Meanwhile the agent can:

• file a ticket and start its run;
• answer the run’s question, with a suggestion or its own text;
• continue, resume or cancel a run, and start a milestone’s run.

Each of these shows in the activity as via token with the token’s name. Some things stay yours whatever the token may do: merging a pull request, answering manual tests, and managing tokens. The agent is told a person does those from the web.

--dry-run on any action prints the request without sending it, for a look before allowing writes.

Have it watch a run

pitwall watch follows a ticket or a whole project and prints one line each time something changes. An agent that reads a command’s output line by line, such as Claude Code with its Monitor tool, is woken by each line and can tell you, or act:

pitwall watch TLY-14 --only problems

prints a line when a gate fails, a question is asked, the run is blocked or paused on a usage limit, or it waits for you: manual tests, a review, the merge. Without --only problems it also prints each step starting and finishing. --until-done ends the watch when the run ends. When the server restarts, the watch prints unreachable once, keeps trying, and reachable when it is back.

Revoking

Revoke the token in Your settings → API tokens when the machine or the agent no longer needs it. The next command it runs exits 2, saying the token is unknown or was revoked.