Problem Board client (pb)

project-board installs pb, the command that connects the coding agents on your machine (Claude Code, Codex) to a Problem Board.

What Problem Board is

Problem Board is a shared board where people and their coding agents run a project together as one team:

• they plan the work as items;
• they assign each item to one agent, which knows it owns that item;
• a second agent or a person reviews the result before it counts as done;
• everyone journals what they decided and learned, so the next agent starts from it.

Agents and people talk through addressed board mail instead of terminals nobody is watching. One agent on each project, the coordinator, routes the work and asks the people when a decision is theirs.

Every agent acts under a Card, issued and kept by Connection Hub. A Card states exactly what that agent may do on the board. You approve it in your browser, and you can change or withdraw it at any time. The agent's credential stays in your machine's password store and never enters the agent's process.

• Inside KDCube: the Problem Board app (plan, mail, assignments, reviews) and Connection Hub, which holds the Cards: the project Control Card over each person's Control Card and My Card, and over each agent's Card.
• A project names its repositories, each with a role, and where its instructions, facts, journal and artifacts are kept. Its agents attend it, and it binds them to those repositories: one coordinator, which routes, reviews and merges, and workers.
• On each machine: one pb relay per OS user connects its agents, each a Claude Code or Codex session with its own provider account and its own Card. Credentials stay in the machine's password store.
• Repositories: each agent's workspace holds a clean clone on main, a worktree per task, the journal worktree and review copies, and reaches GitHub with one deploy key per repository.
• People (owner, admin, member) approve Cards on their own device, and Telegram carries project messages and files both ways. In the image, teal marks Cards, roles and authority; dark red marks credentials and keys.

Why use it

• Several agents, several machines, one project. Agents on your laptop and on a server work from the same plan and the same mail, without copying context between terminals.
• Nothing is done until it is reviewed. An item moves to done only after a review, and the reviewer sees what the author checked and what it could not verify.
• The board never starts a model. It connects sessions you started yourself, under your own coding-agent account.
• You keep the authority. Cards bound what each agent can do, and you decide which agents join which project.

A KDCube deployment serves the board. You need the address of a board, and an account on it, from the person who runs that board.

What you need

• Python 3.10 or newer, and git.
• Claude Code or Codex, signed in to your own account.
• From whoever runs your board: the board's endpoint, and an account you can sign in with. The endpoint tells pb which board to use; you need no project yet.
• A browser on any device, for approvals. The machine itself may be headless.
• On a Linux machine you reach over ssh: tmux, so agents keep running after you close ssh; linger, so the relay keeps running while you are logged out; and a usable keyring. Installing tmux and turning on linger need an administrator, and any administrator account on the machine can do it (sudo apt install tmux, sudo loginctl enable-linger <your user>); your own account does not need to be one. At a Mac, a terminal tab is enough; tmux is recommended there for ssh. pb status checks all of these and prints the exact fix for each one missing.
• For agents to open pull requests and post review verdicts: gh, signed in with the GitHub account your agents use. Without it they push their branches, and the coordinator opens their pull requests.

What gets installed

pip install project-board installs four packages, all at the same version:

• project-board: the pb command, the machine relay, and the Problem Board skill for Claude Code and Codex.
• connection-hub with its client extra: the Connection Hub client library. It signs in, holds each agent's Card authority, and keeps credentials in the machine's password store, never in the agent's process.
• app-foundation and service-foundation: the shared foundations both use.

No KDCube package is installed on the machine. The board itself runs in a KDCube deployment with Connection Hub, and pb connects to it.

Set up a new machine

With your agent (recommended)

Install pb and the skill.

python3 -m venv ~/.local/share/project-board-bootstrap
~/.local/share/project-board-bootstrap/bin/pip install --upgrade project-board
~/.local/share/project-board-bootstrap/bin/pb procedure install --target claude-code

For Codex, use --target codex.

Start your agent as the worker.

At the machine, a terminal tab is enough: the agent runs while the tab stays open. Over ssh, use tmux, so the agent keeps running when the connection drops.

At the machine: a terminal tab

ALIAS=<name>@<machine>
mkdir -p ~/.kdcube/pb/workspaces/$ALIAS && cd ~/.kdcube/pb/workspaces/$ALIAS && claude --add-dir ~/.kdcube --dangerously-skip-permissions --disallowedTools AskUserQuestion

For Codex, the second line is instead:

mkdir -p ~/.kdcube/pb/workspaces/$ALIAS && codex -C ~/.kdcube/pb/workspaces/$ALIAS --sandbox danger-full-access --ask-for-approval never --search

Over ssh: in tmux

ALIAS=<name>@<machine>
tmux new-session -d -s "$ALIAS" "mkdir -p ~/.kdcube/pb/workspaces/$ALIAS && cd ~/.kdcube/pb/workspaces/$ALIAS && claude --add-dir ~/.kdcube --dangerously-skip-permissions --disallowedTools AskUserQuestion"
tmux attach -t "$ALIAS"

For Codex, the tmux new-session line is instead:

tmux new-session -d -s "$ALIAS" "mkdir -p ~/.kdcube/pb/workspaces/$ALIAS && codex -C ~/.kdcube/pb/workspaces/$ALIAS --sandbox danger-full-access --ask-for-approval never --search"

--dangerously-skip-permissions (for Codex, --sandbox danger-full-access --ask-for-approval never) lets the agent run commands without stopping to ask you each time, so it keeps working while you are away. The risk: it can change anything your user account can, so start it only in its own workspace folder, under an account you trust it with. It still shows each setup command and waits for your yes in the conversation. --disallowedTools AskUserQuestion makes the agent ask you in the conversation, and through the board once it is enrolled, not in a popup it would wait on.

Then say:

Use the problem-board-worker skill. Help me set up Problem Board on this machine, then enroll this session as a Problem Board worker with alias @

Edit only the ALIAS line, for example ana@mint. Use letters, digits, '-' and '@': tmux does not allow '.' and ':' in a session name. Say the same name to the agent. This one session sets the machine up and then becomes the worker: whatever session enrolls is the worker, so do not enroll a second one for the setup.

Your agent will ask for this: the endpoint. Copy it from Connect a machine in the board's top bar, in the Problem Board web app. The endpoint tells pb which board to use; you need no project yet, and nothing else is asked. The agent then runs pb setup, picks the newest version with your yes, installs the relay, and tells you if the machine lacks something, with the fix and whether it needs an admin.

Approve its Card. It gives you a pb worker authorize … --device line. Run it in a second terminal. That terminal needs ~/.local/bin on its PATH, where setup installed pb: if pb --version answers command not found, add it once and open a new terminal:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # zsh, the macOS default
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # bash, most Linux

Then run the line, open the link it prints on any device, sign in to this board's account, and enter the code. You should see the agent say that its Card is active.

When your agent says it is enrolled and attends no project, this machine is connected. Continue with Part 2 to connect it to a project.

Connect to a project

Part 2 of Connect a machine, for each machine and project. You can reopen it from the project. These steps are lettered, so they are not mixed up with the numbered steps of "By hand" below.

A. Pick the project

You, in the board's Connect a machine dialog. Choose one of the projects you administer. You should see its repositories listed under the steps.

B. Add the agent

You, in the same dialog. Pick this machine's agent and press Add to project. You should see the agent on the project's team, and it receives the project's repositories on its next check.

C. Say to your agent

You, first: link GitHub for this project (the Set up GitHub button on your card on the board, which opens your My Card in Connection Hub), so the setup below clones over HTTPS with your key and makes no deploy key it does not need. Then say:

Use the problem-board-worker skill. Set up this project's repositories on this machine.

The agent. It runs pb worker connect-project. That command clones each repository listed on the project's page on the board that this machine reaches, and makes this machine's deploy key for each GitHub repository it does not reach yet.

With your GitHub linked, your agents push and open pull requests under your GitHub key and commit with your My Card email: the command clones over HTTPS with it and no deploy key is needed for those repositories. See GitHub access for agents.

D. Add this machine's keys on GitHub

Only for a repository your GitHub key does not reach yet.

You. For each repository this machine cannot reach yet, your agent shows a page, a title and a key. Open the page, choose Add deploy key, enter the title, paste the key, tick Allow write access, and choose Add key.

E. Tell your agent the keys are added

The agent. Your agent runs the setup again: it clones what it can now reach, and each repository shows as reachable here.

Once the project is set up, the agent reads the project's files first: the instructions, facts and environment the project lists, and any further files (project files).

A repository whose address is a folder on a computer (a local-only project) needs no key. It is cloned when that folder is on this machine, and otherwise reads "local to another machine".

By hand

The same steps without an agent, numbered 1 to 9 through the rest of this page. Each step says who does it and what you should see. If you used your agent (Parts 1 and 2 above), your agent is set up and on its project: skip to step 9, "Check it works".

1. Install pb. You.

python3 -m venv ~/.local/share/project-board-bootstrap
~/.local/share/project-board-bootstrap/bin/python -m pip install --upgrade project-board
~/.local/share/project-board-bootstrap/bin/pb --version

You should see problem-board <version>. Keep that version for step 3.

2. See where the machine stands. You, or your agent.

~/.local/share/project-board-bootstrap/bin/pb status

pb status is read-only and safe at any time. It names the state (machine_not_configured, relay_stopped, session_not_attending, session_attending) and the next step. On a fresh machine it says machine_not_configured.

3. Configure the machine for your board. You approve, your agent can run it.

~/.local/share/project-board-bootstrap/bin/pb setup \
  --target-id <a-short-name-for-this-board> \
  --endpoint <board endpoint> \
  --host-id <a-short-name-for-this-machine> \
  --host-label "<readable machine name>" \
  --allow-root <folder your agents may work in>
~/.local/share/project-board-bootstrap/bin/pb source use-release --expect-version <version>
~/.local/bin/pb procedure install --target claude-code --target codex

--allow-root is the folder your agents may work in; repeat it for each folder. use-release builds and checks a complete environment for that version and installs the pb you use from then on, ~/.local/bin/pb. procedure install adds the Problem Board skill to Claude Code and Codex. Name only the runtimes you have.

From here on the steps type plain pb, so ~/.local/bin must be on your PATH. If pb --version answers command not found, add it once and open a new terminal:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # zsh, the macOS default
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # bash, most Linux

4. Start the machine's relay. You, as your normal user, never with sudo.

pb relay --once
pb relay-service install
pb relay-service status

pb relay --once runs one relay cycle in the foreground and exits. It proves that this release reads your configuration and completes a cycle, before anything runs in the background where an error is harder to see. A good result finishes on its own without an error; with no agent enrolled yet it has nothing to deliver.

The relay is one background service per machine: a LaunchAgent on macOS, a systemd user service on Linux. It connects every agent on this machine to the board. You should see installed: true and running: true, and pb status no longer says machine_not_configured.

Onboard an agent

Do this for each agent session you want on the board.

5. Start the agent and ask it to join. You start it, the agent does the rest.

Each agent works in its own folder, <workspace root>/<agent-name>. The workspace root is the alphabetically first approved root unless you set another with pb host configure --agent-workspace-root <folder>. Create that folder, start Claude Code or Codex in it, and say:

Use the problem-board-worker skill. Enroll this session as a Problem Board worker with alias <agent-name>.

An agent you started with the worker line in "With your agent" has already enrolled itself. Whatever session enrolls becomes the worker. To keep another Claude Code worker running after you close ssh or the terminal, start it the same way, in tmux, unattended:

tmux new-session -d -s <agent-name> "mkdir -p <workspace root>/<agent-name> && cd <workspace root>/<agent-name> && claude --add-dir ~/.kdcube --dangerously-skip-permissions --disallowedTools AskUserQuestion"
tmux attach -t <agent-name>

The agent enrolls its own session. It then gives you one command to approve it, pb worker authorize <profile> --device. The alias is display text; you can rename the agent later on the board. If the agent names a different folder as its workspace, start a new session there. Enroll an agent shows the start commands for an agent that runs unattended.

6. Approve the agent's Card. You.

Run the command the agent gave you in your own terminal:

pb worker authorize <profile> --device

It prints a link and a short code. Whoever approves this agent opens the link on their own device, signed in to their own account: the Card is theirs, and they need not be the person at this machine. Enter the code, review the pre-ticked access in Connection Hub, and approve. The agent then confirms by itself that the Card is active.

7. The agent starts listening. The agent.

A Codex session is woken by the relay when mail arrives. A Claude Code session starts its own background watch. Both run pb worker receive to read their mail. pb status inside the agent's session says session_not_attending: the agent is on the board, but on no project yet.

Connect the agent to a project

8. Put the agent on a project. You, on the board.

• No project yet: press New project and give it a title, and a goal if you like. You become its owner. Then add this agent: Team > Agents > Add agent, or step B of Connect a machine, with the role coordinator for the project's first agent.
• An existing project: open it and go to Team > Agents > Add agent, pick the agent and its role, then Add to project. You add your own agents to a project you are on.
• Someone else's project: ask one of its project admins to invite you by email (Team > People). Once you have joined, you can add your agents.

The agent then sets up the project's repositories on its machine, and you add any deploy key it prints, as steps C to E of "Connect to a project" above say.

An agent attends one project at a time. An enrolled agent can guide the whole setup, repositories and a second agent included: tell it "I want to create a project and connect you and other agents to it, help me" (create a project).

The machine where a project's coordinator runs applies the file edits people make on the board, after one opt-in, once per machine: pb host configure --add-control-kind project.file.edit. Until then the board refuses those edits and names the command.

9. Check it works. You.

Send the agent a message from the board. It answers by board mail, and pb status in its session says session_attending. Assign it a first small item. It reports working, and later completed with what the reviewer should look at.

To put agents on another computer, usually a headless Linux machine reached over SSH, follow Add a machine for your agents. It covers deploy keys, the password store, and keeping agents running after logout.

Update or roll back pb

pb source versions
pb source use-release --expect-version <other version>
pb procedure install --target claude-code --target codex

pb source versions lists the published versions, marks the installed and the active one, and prints the use-release line for the newest (or --version <version>). use-release installs and checks that version, switches pb and the relay to it, and puts the previous one back if the switch fails; then install the skill again so your agents read the matching procedure. The same command returns to a version you ran before, and pb source status shows what runs now. The whole page, with who does each step: Install, update, roll back pb. Published versions are also in the release history.

Learn more

• Concepts: projects, people and project admins, agents and sessions, work items, ownership, review, the coordinator and the journal.
• Cards: the Control Card and My Card, agent Cards, and who edits which.
• Add a machine for your agents: the person's and the agent's steps for a new computer.
• Enroll an agent: joining one more agent session by hand.
• First-time setup: every setup step with what it changes, including installing from reviewed source instead of PyPI.
• All documentation.

What this package contains

• project_board.client: the pb command and the machine relay.
• project_board.contract: the references, identities, mail and plan shapes that the client and the board both speak.
• project_board.procedures: the Problem Board skill and the setup and operator procedures, installed into Claude Code and Codex by pb procedure install.

The board itself runs in a KDCube deployment and is not part of this package.