Skip to content
v0.1.0MIT

One person's stack for running a repo's tasks as agent threads under T3 Code: a home plans and briefs, a crewmate does one task and opens its pull request, a reviewer reviews it, and jbus and jmerge do the routine work.

jstack

jstack turns a repo's backlog into reviewed, merged pull requests while you do something else. You tell a home thread in T3 Code what you want done. It plans the work with you, writes a brief for each task, and starts an agent thread for each one in a worktree of its own. Each thread does its task, opens a pull request, has it reviewed, and fixes what the review finds. jmerge merges each pull request once it is reviewed, fixed and green. You answer the questions only you can answer, and the rest goes on without you.

Status: experimental. Commands, flags, files and skills can change with no notice and no migration.

It is for a developer who uses Claude Code and wants more than one agent at work on a repo at a time. Every thread spends tokens on your Claude plan. One task takes at least two threads, a crewmate and a reviewer. jgauge session prints what a thread cost.

How a task flows through jstack: a home plans and writes a brief, a scout researches when needed, a crewmate does the one task and opens the pull request, a reviewer sends findings back, and jbus runs jmerge, which merges to main.

  • A home thread plans with you, writes a brief for each task, and launches a thread for it.
  • A crewmate thread does the one task in its brief, opens the pull request, and fixes what the review finds.
  • A scout thread researches a question with read-only tool calls before a task is briefed.
  • A reviewer thread reviews one pull request and fixes nothing.

How a task flows has every step of the picture, and what you are asked for along the way.

Each thread keeps its records in a state directory outside the repo. A thread can end at any time, and the next one starts from those files. A thread does reversible work without asking. It waits for you only before a step that deletes data, rewrites history, spends money, touches prod or real users, changes access or secrets, or publishes. A question only you can answer becomes a gate. The thread takes a default, carries on, and asks you. Your answer closes the gate, and with no answer the gate keeps its default. Eleven commands do the routine work with no model, and Reference lists them all.

Requirements

jstack runs only when every hard need is met. jinstall --doctor checks each one.

NeedLevelNotes
Linux or macOShardSupported: macOS on Apple Silicon, and Windows in WSL2.
T3 CodehardThe desktop app the threads run in, with Claude Code as their agent, from t3.codes (how to install it): stable 0.1.2, or nightly 0.1.2-nightly.20261022.3526 or newer.
Claude CodehardThe claude command on PATH.
uvhardIt installs the eleven commands as one tool, jstack.
githard2.31 or newer.
jqhard1.6 or newer.
gh, signed inhardgh auth login. The threads open pull requests with it, and jmerge merges with it.
jbus, signed inhardjbus t3 login, once jbus has a project, since jbus reads your go from T3 Code.
Role poolshardjroles --check.

The commands run on Python 3.12 or newer. uv uses a Python it finds on the machine, and downloads one when it finds none. The commands also install tzdata, their one package, and read your time zone from it where the system has no zone files.

An optional need switches a layer on. jstack runs without it.

NeedWhat you lose without it
jbus and its configNothing runs between your threads, so the work moves only while a home is open, and you run jmerge yourself.
systemd --user, or launchd on macOSNo background jobs. The install enables these timers: the jbus pass each minute, jbus-merge every 10 seconds, the check for a missing pass, jgauge-limits and jgauge-sample, and jroles-mirror. It enables the week's and the day's CI reports (jbus-ci.timer, jbus-ci-day.timer), the relay and the backup only once their config is there.
The limits file, ~/.local/state/claude/limitsjgauge room cannot see the plan's five-hour and weekly limits, so only the machine's readings hold a launch back. jinstall sets a status line that writes the file, unless you have a status line of your own.
The backup: a private remote and gitleaksThe homes' state directory is not pushed anywhere. With an origin on ~/.local/state/home and gitleaks on the machine, a timer commits and pushes it twice a day (Back up the homes' state).

The threads run on Claude Code, and the install also links the skills for Codex and Cursor. It writes outside jstack's own folders: skill links in ~/.claude/skills, ~/.codex/skills and ~/.agents/skills, hook entries and keys in ~/.claude/settings.json, ~/.codex/hooks.json and ~/.cursor/cli-config.json, the units in ~/.config/systemd/user or ~/Library/LaunchAgents, and each config it finds missing under ~/.config. jinstall --uninstall takes its links, hook entries, keys and units away. jinstall lists every file, and AI co-author trailers says which keys it sets.

Quickstart

In this tutorial we install jstack, point it at a repo of yours, and watch it merge one pull request its threads wrote.

  1. Install jstack from main and set it up. The script needs only curl and a shell.

    curl -fsSL https://raw.githubusercontent.com/JoshuaHayesWasHere/jstack/main/install.sh | sh
    

    The script installs uv when it is missing, installs the eleven commands as the uv tool jstack, and runs jinstall --setup. With uv already there, you can do the same by hand:

    uv tool install git+https://github.com/JoshuaHayesWasHere/jstack@main
    jinstall --setup
    

    Once a release exists, its script installs it:

    curl -fsSL https://github.com/JoshuaHayesWasHere/jstack/releases/latest/download/install.sh | sh
    

    Setup prints one line for each need, and Setup says what each line means. While a step is left to you, the last line starts with setup: <n> needs you:. Run each command it names, such as gh auth login, then run setup again until that line is gone. A missing optional line is a layer you may leave off.

  2. Check the install.

    jinstall --check
    

    Each hard part prints a line that starts with ok. An old optional or missing optional line is a layer you may leave, and makes the command exit 1.

  3. Check the machine.

    jinstall --doctor
    

    You see a line for each requirement, then the lines of step 2, and doctor: ok last once every hard need is met. Every missing or old line has an entry in Troubleshooting.

  4. Pick the repo that you want work done in. It needs a GitHub remote that gh can push to, and a CI check named check that runs on each pull request, since jmerge merges only once that check passes. Where it has none, step 5 commits one on a branch jstack-check: push it and merge it. GitHub's guide Quickstart for GitHub Actions shows how to add a setup step it may need. To wait on other checks too, list their names in required-checks in the state directory of step 5 (What ready means).

  5. Open T3 Code, start a thread in any project, and type this with the path of the repo's main checkout.

    /new-home <path>
    

    You see one line for each part of the repo's first home: done, already, or needs you with what to do. It makes the state directory, ~/.local/state/home/<repo>, where <repo> is the checkout's folder name. It adds the repo to T3 Code as a project and to the jbus config, and links jleak's git hooks, which keep what must stay private and AI co-author lines out of pushes and commits. It writes the repo's check command to fresh-check there (make check, where the repo has that target), and the workflow of step 4. Then its sign-in line says needs you until you run jbus t3 login, a hard need from now on. Last, it starts the home thread, and you see a short status of the repo there. Once that home ends, the next thread you open in the project becomes the home.

  6. Tell the home one small task, and give the go. It asks you about the plan and writes a brief. Nothing starts until you say go, which the home keeps with jbus plan go. Then it starts a crewmate thread, with a worktree of its own, in T3 Code's thread list.

  7. Watch the crewmate. You see it do the task, run fresh-check's check command, and open a pull request. Once the pull request's check has passed, it starts a reviewer thread. Then it fixes what the review found, and says the pull request is fixed and green.

  8. Watch it merge. Step 5 put the repo in the jbus config, so jbus runs jmerge within seconds of the last check ending. jmerge merges each pull request that is reviewed, fixed and green, then removes its worktree and its branch. The reviewer thread's review is the approval, so no person approves on GitHub. jmerge --check in the main checkout prints why each open pull request waits.

Where jbus does not run, merge from the repo's main checkout yourself:

jmerge

After /nohome merge in a repo, jmerge merges nothing there and says auto-merge is off for this repo: the merges are yours until /nohome merge on. To add jleak's git hooks to another repo, run jinstall --repo in it (Git hooks in your repos).

To remove jstack from the machine, run jinstall --uninstall, then uv tool uninstall jstack.

Reference

Each command has one page.

CommandPageWhat it does
jbriefsfeatures/jbriefs/docs/jbriefs.mdWrites one HTML page of every home, plan and brief.
jbusfeatures/jbus/docs/jbus.mdDoes a home's routine work from a timer, so a repo can run with no home thread.
jdriftfeatures/jdrift/docs/jdrift.mdLists what changed upstream in the files taken from pstack.
jgaugefeatures/jgauge/docs/jgauge.mdCounts what a thread cost in tokens, and says whether there is room for one more.
jinstallfeatures/jinstall/docs/jinstall.mdInstalls, checks and removes jstack on a machine: install.sh in a checkout, and the jinstall command from a release.
jleakfeatures/jleak/docs/jleak.mdFinds what must not leave the machine for a public repo, before a push or a pull request, and keeps AI co-author trailers out of commits and pull requests.
jmergefeatures/jmerge/docs/jmerge.mdMerges every pull request that is reviewed, fixed and green.
jpackfeatures/jpack/docs/jpack.mdChecks a context pack.
jrolesfeatures/jroles/docs/jroles.mdPicks the model for a role from the role map.
jstackfeatures/jstack/docs/jstack.mdRuns the other commands: jstack leak runs jleak.
repo-standardfeatures/repo-standard/docs/standard.mdThe standard a repo's layout, feature map and docs hold to, and the guards any repo runs from its .repo-standard.yml to hold them.
PageRead it to
ConfigurationFind every file you write, with each key, its default and who reads it.
TroubleshootingFix a line the doctor or jinstall --check printed, a thread that did not become a home, or a wait: from jgauge room.
The ChefThe agent outside a home that keeps the queue with jbus queue.
HooksSee what the start hook and the sends hook do.
StateFind the files a home and its threads keep, and who tells whom.
Playbooks, principles and templatesGive a task numbered steps.

Skills

features/ holds every skill, and the catalog lists each one by its feature. Several names come from pstack, the agent skills by Lauren Tan for Cursor that jstack takes its principles from: poteto-help, setup-pstack and the jdrift command. Eight skills run the flow, and poteto-help is the way in. Each SKILL.md is the full text of what its thread does.

SkillTyped asWhat the thread does
home/home, /home <scope>Becomes the repo's home, or the home of one scope. It reads what jbus holds, plans with you, writes each brief and launches its crewmate. It does none of the work itself.
crew/crew <slug>Becomes a crewmate. It does the task in tasks/<slug>.md in its own worktree, opens the pull request when the brief says so, appends its Result to the brief, and stays on the pull request.
scout/scout <slug>Becomes a scout. It answers the questions in scouts/<slug>.md, appends its report, and writes a crewmate's brief or a visual page when the request asks for one. It changes nothing in the repo.
pr-review/pr-review, /pr-review <slug>Launches one review thread in the crewmate's worktree. It reads the diff, judges what it found, and proves with one command the fact that makes the change safe. It runs no test suite.
handoff/handoffArchives a home: it hands what the home has out to the uncategorized home and starts no next home.
nohome/nohome, /nohome repo, /nohome on, /nohome merge, /nohome merge onOpts this thread, or every new thread in the repo, out of the automatic home, or switches it back on. With merge it switches the repo's automatic merge off or on.
new-home/new-home <repo>Sets up a repo's first home, from any thread: its state directory, its T3 Code project, its table in the config of jbus, what it lacks for a merge, and its home thread. It does only what is missing.
poteto-help/poteto-help <question>, /poteto-help <slug>Answers a help question and starts no work. It names the role to type, the playbook and the skills that fit a brief or a question, each with its file. "Get set up" points at the Quickstart above.

The others are loaded by name. /setup-pstack runs jinstall --setup and the doctor on this machine, or install.sh --setup in a checkout, and reports what is left for you. /expert <name> makes a thread the expert of one subject. The rest are tools, such as /architect, /create-formal-verification-skill, /unslop and /technical-writing. THIRD_PARTY.md lists where each came from.

Contributing

The repo takes issues and pull requests. CONTRIBUTING.md says how to report a bug, open a pull request, and run the checks. SECURITY.md says how to report a vulnerability.

License

MIT. See LICENSE.