Stagent
DocsFAQ
Quickstart

Stagent · Help

FAQ

Stagent is a live viewer for sessions and a hub of templates driven by the stagent Claude Code plugin. Everything else answered below.

01

Getting started

#What is this?

A live viewer for sessions and a hub of templates driven by the stagent Claude Code plugin. You run /stagent:start in your terminal; this site shows a live timeline of the run — every stage your template defines — with each artifact, diff, and transition, and hosts a library of reusable templates.

#What is a session?

A single live run of a workflow on your machine. /stagent:start creates one; the plugin mirrors its state (current stage, epoch, artifacts, diff) to this webapp so you get a live URL at /s/<id>. Sessions progress through stages until they reach a terminal (complete, cancelled, or escalated) and then stop. If you're signed in, they show up under /me/sessions. Think of a session as one cooking of a recipe.

#What is a template?

The reusable definition a session runs against. A template bundles a workflow.json (stage graph + transitions) and one markdown file per stage (the instructions a subagent follows). Templates published to the hub are addressable as cloud://author/name; anyone with access (per the template's visibility) can instantiate one by running /stagent:start --flow=cloud://author/name. Your own templates show up under /me/workflows. Think of a template as the recipe; each session is one cooking of it.

#Does Stagent run my code?

No. Your Claude Code session runs everything locally on your machine. The plugin just mirrors read-only state here so you can watch it, resume it elsewhere, and share templates. Your source files never leave your laptop — only stage reports, state-machine status, and (for worktree-modifying templates) git diff text get synced.

#Do I need an account?

To browse the hub and watch sessions someone has shared the URL of: no. To publish your own templates, resume sessions across machines, or favourite things: yes. Sign in with GitHub, Google, or Apple.

#What’s a good first template to try?

Start with the default: /stagent:start "<your task>" in cloud mode pulls cloud://demo from the hub — currently a plan / execute / verify / review / QA loop, though the hub version may evolve. Once you've watched one end-to-end, check the cookbook for recipes that target specific Claude Code failure modes (root-cause analysis, strict TDD, scope lock-down, visual QA, perf gate, and more).

#Can I build my own template?

Yes — that's the main differentiator. A template is two things: a workflow.json that declares your stage graph (initial stage, terminal stages, per-stage transitions keyed on whatever result strings your stages produce — e.g. done, PASS / FAIL, approved) plus one markdown file per stage with the instructions the subagent follows. Publish it and anyone (or your future self on another machine) can invoke it via cloud://you/name. Stages can loop, branch, or gate — whatever your process actually is, not just plan → execute → verify.

#How do I create one?

Two paths — pick the one that matches how much you’ve thought it through:

  • AI build (recommended): /stagent:create "<describe what the template should do>" — stagent interviews you, designs the stage graph, writes workflow.json plus every stage file, and publishes to the hub.
  • Manual form: head to /hub/new and fill in the name, paste workflow.json, then write each stage markdown. Best when you already know the exact stage graph you want.

Both publish as private by default — only you can see or run it. Flip to unlisted to share the URL (or cloud://you/name ref) with collaborators without listing it on the hub, or public to make it discoverable by anyone.

02

How it works

#Cloud mode vs local mode — what’s the difference?

Default is cloud: state (stages, artifacts, diffs) is mirrored to this webapp so you get a live UI and cross-machine resume. Pass --mode=local to keep everything under <project>/.stagent/ — no network, no UI, just files.

#What gets uploaded to the server?

Stage reports (markdown), state-machine status (current stage, epoch, result), and — for templates that touch the worktree (modifies_worktree: true) — git diff baseline..HEAD as text. Your source files stay in your git repo. The files that appear on the viewer are the ones the subagent produces — plans, reviews, QA reports, etc.

#Can I actually watch it work in real time?

Yes — that’s the main reason cloud mode exists. When you start a session the terminal prints a UI URL. Open it, and the stage timeline, artifact viewer, and diff panel update live over SSE as the subagent works. It’s basically a CI dashboard for one Claude run.

#My laptop crashed mid-session. What now?

If you were in cloud mode: git push on the old machine (if reachable), then on the new one git pull and run /stagent:continue --session <id>. The plugin verifies the new workdir has the same git history before resuming — no silent stale-code runs.

#Can I pause and continue across machines?

Yes. /stagent:interrupt pauses immediately, even mid-stage. On any other machine that's signed in to the same account, /stagent:continue --session <id> mirrors the state down and resumes — provided the git history matches (you need to push/pull your code separately; the plugin doesn't copy source).

#Can I edit a template I already published?

Yes. Same command does both create and edit:

/stagent:create --flow=cloud://you/name \
  "add a 'deploy-dry-run' stage after qa"

#Who can see my templates and sessions?

Templates have three visibility levels:

  • public — listed on the hub and discoverable by anyone.
  • unlisted — not listed, but anyone with the URL or cloud:// ref can fetch it. Good for sharing with collaborators without making it searchable.
  • private — only you can see or use it. This is the default for new publishes; flip it when you’re ready to share.

Sessions have two visibility levels. Signed-in users' sessions are private by default — URL alone doesn't grant access (others see a “session is private” page) and your sessions are listed at /me/sessions. The owner can flip a session to unlisted via the Share button on its page, after which anyone with the URL can view it. Anonymous plugin runs (no signed-in user) skip this — they're always URL-viewable, so sign in before running if you want privacy.

#Does it work with any language or framework?

Yes. The plugin is language-agnostic. Your workflow.json declares the stage graph; the actual build, test, and lint commands live in each stage's .md instructions, not in the plugin.
03

How it differs

#Why not just put the rules in CLAUDE.md?

CLAUDE.md rules sit in the system prompt and the model decides per-turn whether to honour them. Over a long session that's exactly what doesn't happen — early turns follow the rules, later turns drift as context dilutes. A workflow re-injects each stage's instructions fresh on entry, and the state machine — not the model — decides whether the pass/fail criteria are met. When a criterion fails, the machine loops back per the workflow's transition table; the model doesn't get to say “close enough.”

#Why not trust Claude Code when it says it’s done?

Because the model writing the code shouldn't be the one judging it. Stagent's pass/fail evaluation runs in a separate stage — often a different subagent entirely — that reads the artifact against criteria you wrote and either advances or loops back. The model finishing the implementation never gets to declare itself done.

#Why not just watch progress in the terminal?

Because you’re usually not at the terminal — you’re in a meeting, on your phone, or pairing with a teammate. Stagent prints a browser URL when the session starts. Open it from anywhere and the stage timeline, file diffs, and artifacts update live. Same URL works for a teammate reviewing after the fact.

#Why not use /resume in Claude Code to continue on another machine?

/resume is scoped to the machine where the session started — it reads local conversation history that doesn’t sync. /stagent:continue --session <id> picks up exactly where you left off on any signed-in machine, with a git-history check so you don’t accidentally resume against stale code.

#Why not scroll through the Claude Code chat log to find an earlier artifact?

Because a Claude Code conversation is one long log — finding the review report from three iterations ago means scrolling and guessing. Stagent stores every stage’s output as a standalone file with an epoch stamp. Jump to the plan from epoch 2 or the QA report from epoch 5 as a document, not a chat quote.

Still stuck? Open an issue on the plugin repo.