How Pitwall works

Pitwall has two parts: one core, the server everyone uses, and any number of runners, the machines where agents run. Everything that needs to be durable lives either in a repository or in the core’s PostgreSQL database.

Figure 11:1Scroll sideways

Figure 1.

The core and its runners. Arrows point from the side that opens the connection: runners connect out to the core’s runner gateway; the core never reaches into a runner.

The core

One Go server, one image, backed by PostgreSQL. It holds:

Part	Does
HTTP API and live updates	Serves the web UI and keeps its screens current while they are open
Pipeline engine	Decides every next step of every ticket, runs each step’s gate, and asks a person when one is needed
Runner gateway	Hands jobs to runners and takes back their events and results
Repository mirror	A read-only copy of each project’s repositories, fetched from GitHub, that the UI renders documents from
Notifier	Tells a person on Telegram when something waits for them
GitHub port	Opens and reads pull requests, reads CI, and merges a pull request a person approved

Runners

A runner is a small Go binary on a machine that can build the project: a Linux server for a web project, a Mac for an Xcode one. It takes jobs whose project needs match its labels, runs Claude Code in a local checkout, streams what the agent does back to the core, and commits and pushes.

A runner opens every connection. It dials out to the core and asks for work; the core never reaches into a runner. A laptop behind NAT or a server in another country works the same, with no inbound port and no VPN.

Who writes, who merges

Action	Who
Changes a working tree, commits, pushes	A runner, and only a runner
Opens and updates the pull request	The core, through the GitHub App
Merges the pull request	The core, through the GitHub App, and only after a person approved it

How documents travel

Git carries them. A runner pushes the ticket’s branch after every commit; the core fetches into its mirror and renders the Markdown from there. No second copy of a document exists outside git.

What lives where

In the repository	In PostgreSQL
Project documentation: tech spec, milestones and phases, decisions, manual tests	Tickets, runs, agent events, tokens and costs
Each ticket’s records, under docs/tickets/<KEY-N>/	Users, projects and their members
	Chats with an agent, and the files attached to tickets and chats

Neither copies the other. Milestones and phases are read from the repository and never stored as rows, so work advanced from a terminal shows up as it is, and a repository stays complete and workable without Pitwall.

Code coordinates, agents compute

Step order, gates, loops and routing are Go code. No agent decides which step runs next: an agent does one step’s work, and a deterministic gate checks the result before the engine moves on. The pipeline describes the steps.