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.
| Need | Level | Notes |
|---|---|---|
| Linux or macOS | hard | Supported: macOS on Apple Silicon, and Windows in WSL2. |
| T3 Code | hard | The 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 Code | hard | The claude command on PATH. |
uv | hard | It installs the eleven commands as one tool, jstack. |
git | hard | 2.31 or newer. |
jq | hard | 1.6 or newer. |
gh, signed in | hard | gh auth login. The threads open pull requests with it, and jmerge merges with it. |
jbus, signed in | hard | jbus t3 login, once jbus has a project, since jbus reads your go from T3 Code. |
| Role pools | hard | jroles --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.
| Need | What you lose without it |
|---|---|
jbus and its config | Nothing runs between your threads, so the work moves only while a home is open, and you run jmerge yourself. |
systemd --user, or launchd on macOS | No 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/limits | jgauge 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 gitleaks | The 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.
-
Install jstack from
mainand set it up. The script needs onlycurland a shell.curl -fsSL https://raw.githubusercontent.com/JoshuaHayesWasHere/jstack/main/install.sh | shThe script installs
uvwhen it is missing, installs the eleven commands as theuvtooljstack, and runsjinstall --setup. Withuvalready there, you can do the same by hand:uv tool install git+https://github.com/JoshuaHayesWasHere/jstack@main jinstall --setupOnce a release exists, its script installs it:
curl -fsSL https://github.com/JoshuaHayesWasHere/jstack/releases/latest/download/install.sh | shSetup 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 asgh auth login, then run setup again until that line is gone. Amissing optionalline is a layer you may leave off. -
Check the install.
jinstall --checkEach hard part prints a line that starts with
ok. Anold optionalormissing optionalline is a layer you may leave, and makes the command exit 1. -
Check the machine.
jinstall --doctorYou see a line for each requirement, then the lines of step 2, and
doctor: oklast once every hard need is met. Everymissingoroldline has an entry in Troubleshooting. -
Pick the repo that you want work done in. It needs a GitHub remote that
ghcan push to, and a CI check namedcheckthat runs on each pull request, sincejmergemerges only once that check passes. Where it has none, step 5 commits one on a branchjstack-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 inrequired-checksin the state directory of step 5 (What ready means). -
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, orneeds youwith 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 thejbusconfig, 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 tofresh-checkthere (make check, where the repo has that target), and the workflow of step 4. Then its sign-in line saysneeds youuntil you runjbus 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. -
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. -
Watch the crewmate. You see it do the task, run
fresh-check's check command, and open a pull request. Once the pull request'scheckhas passed, it starts a reviewer thread. Then it fixes what the review found, and says the pull request is fixed and green. -
Watch it merge. Step 5 put the repo in the
jbusconfig, sojbusrunsjmergewithin seconds of the last check ending.jmergemerges 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 --checkin 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.
| Command | Page | What it does |
|---|---|---|
jbriefs | features/jbriefs/docs/jbriefs.md | Writes one HTML page of every home, plan and brief. |
jbus | features/jbus/docs/jbus.md | Does a home's routine work from a timer, so a repo can run with no home thread. |
jdrift | features/jdrift/docs/jdrift.md | Lists what changed upstream in the files taken from pstack. |
jgauge | features/jgauge/docs/jgauge.md | Counts what a thread cost in tokens, and says whether there is room for one more. |
jinstall | features/jinstall/docs/jinstall.md | Installs, checks and removes jstack on a machine: install.sh in a checkout, and the jinstall command from a release. |
jleak | features/jleak/docs/jleak.md | Finds 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. |
jmerge | features/jmerge/docs/jmerge.md | Merges every pull request that is reviewed, fixed and green. |
jpack | features/jpack/docs/jpack.md | Checks a context pack. |
jroles | features/jroles/docs/jroles.md | Picks the model for a role from the role map. |
jstack | features/jstack/docs/jstack.md | Runs the other commands: jstack leak runs jleak. |
repo-standard | features/repo-standard/docs/standard.md | The 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. |
| Page | Read it to |
|---|---|
| Configuration | Find every file you write, with each key, its default and who reads it. |
| Troubleshooting | Fix a line the doctor or jinstall --check printed, a thread that did not become a home, or a wait: from jgauge room. |
| The Chef | The agent outside a home that keeps the queue with jbus queue. |
| Hooks | See what the start hook and the sends hook do. |
| State | Find the files a home and its threads keep, and who tells whom. |
| Playbooks, principles and templates | Give 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.
| Skill | Typed as | What 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 | /handoff | Archives 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 on | Opts 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.