Shogun Flow

# why

# what you get

• 01

  One agent per issue

  Label a GitHub issue ready and a Claude Code (or Codex) session picks it up, on a branch of its own. A cap decides how many run at once; the rest wait their turn, and an issue another one blocks waits for it.

• 02

  A worktree each

  Every run happens in its own git worktree, so agents never step on each other or on the checkout you're working in.

• 03

  One inbox

  Only what needs you, most urgent first: a question that pauses an agent, a permission, a plan to approve, a pull request to merge. Each says in one line what it needs, with its facts and its own buttons: lettered choices, allow, merge.

• 04

  Ends on a green pull request

  The agent opens a pull request and waits for its checks. A reviewer reads it before you, and red CI goes back to it. Merge with one click on the board, or let Shogun Flow merge what passed: when parallel pull requests collide, it brings them up to date or sends a fixer, then merges them one by one. A merge that was wrong is one revert away, and the revert waits for you.

• 05

  Calm at a glance

  Home says three things: what needs you, whether the work is moving, and what each project is doing in one plain line. Reviewed pull requests come with two plain lines on what they're for and what's on you. The stages, from waiting to merged, are a click away.

• 06

  Plan with your product manager

  Each project has a product manager. On Plan it opens with a short briefing and suggests a goal when you have none; ask it anything, or start a triage session and sort the backlog one issue at a time, each with its call and why. Nothing moves until you click.

• 07

  Everything on the record

  The Activity page lists everything Shogun Flow did in a project: runs, reviews, merges, labels, settings and HR's changes, filtered by kind. While auto-merge is on, every page says so, and the status line says when it last looked for work and when it looks next.

• 08

  Runs that survive

  Sessions live in tmux. Close the board or restart the daemon and every run carries on. Attach to any of them for the full terminal. shogun-flow stop stops the daemon, the runs carry on, and shogun-flow install keeps it running across reboots. A laptop that slept is noticed, not mistaken for stuck agents.

• 09

  Set up, then start

  A new repository opens on a setup, one step at a time: what it needs, the tracker, the agent, your issues and your phone. It says what starting would pick up, and nothing runs until you press start. shogun.config.json is committed, so a team shares one setup.

• 10

  You choose how agents act

  Prompts off: agents work on their own behind a guard that refuses merges, force-pushes and other dangerous commands. Prompts on: every command is a card. Asked on every machine: a teammate's clone never inherits prompts off or auto-merge.

• 11

  Roles are markdown

  A role is a prompt with a few lines of frontmatter, including when it runs: on a ready issue, after the builder, after a merge or on a schedule. Copy one into your repository, edit it, commit it.

• 12

  A team, and HR to change it

  The Team page shows each role at work: what's live, its runs, its success rate and what the agents are saying. To change the team, tell HR. It asks what it needs and writes the change.

• 13

  Every project, one board

  One daemon serves every repository on your list. Each gets its own group of pages in the menu, and the overview adds them up.

# keyboard

• jkNext and previous card
• abcAnswer with a choice
• ↵Open the run behind a card
• ?Help: shortcuts, labels, cards, the guard

# install

# not on npm yet
$ npx shogun-flow

# stack

# how it works