hangar
CLAUDE.md1 starsChanged 3 months agoMITView on GitHub
A mouse-driven board that turns Jira tickets into Claude Code agent sessions. A React board shows Jira tickets as Kanban columns; assigning an agent/skill to a card spawns a Claude Code session via @anthropic-ai/claude-agent-sdk and streams it back live. See README.md for the user-facing feature tour, docs/ for detailed guides (e.g. docs/AI_WORKFLOW.md), and ../Hangar-SPEC.md for the full plan. This is a monorepo with three package.jsons: root (orchestration scripts only), server/, and web/. Workspaces are NOT used — each installs into…
- Reads credentials
In this repository6 other files it gives its agents.
- aiwf-syncSkill
- config-fieldSkill
- docs-updateSkill
- hangar-validateSkill
- releaseSkill
- smokeSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 27
Run from the repo root:
- Distinctive: line 41
Before committing or opening a PR, always run all checks and confirm they pass:
- Distinctive: line 48
Do not open a PR if any command fails.
- Very specific: line 78
When a ticket is assigned an agent/skill, sessions.ts spawns a query():
- Very specific: line 125
Never commit .env, hangar.config.json, or anything under .hangar/ — all gitignored (secrets / personal board config / runtime data).
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hangar
A mouse-driven board that turns Jira tickets into Claude Code agent sessions. A React board
shows Jira tickets as Kanban columns; assigning an agent/skill to a card spawns a Claude Code
session via @anthropic-ai/claude-agent-sdk and streams it back live.
See README.md for the user-facing feature tour, docs/ for detailed guides (e.g.
docs/AI_WORKFLOW.md), and ../Hangar-SPEC.md for the full plan.
Layout
hangar/
hangar.config.json # boards (Jira keys, columns), agentsDir, run settings — hot-reloaded
hangar.config.example.json # committed template; copy to hangar.config.json (the real one is gitignored)
.env # Jira creds + PORT (copy from .env.example; never commit)
.hangar/ # runtime data dir (gitignored): runs/, workflows/, and aiwf/ board cards
server/ # Node + TypeScript + Express: Jira adapter, agent/skill registry, SDK runner
web/ # React + Vite + TypeScript: the board UIThis is a monorepo with three package.jsons: root (orchestration scripts only), server/,
and web/. Workspaces are NOT used — each installs into its own node_modules.
Commands
Run from the repo root:
npm run install:all— install server + web deps (root deps come from a plainnpm install)npm run dev— start server (:3001) and web (:5180, override withWEB_PORT) viaconcurrentlynpm run dev:server/npm run dev:web— run one side alonenpm run typecheck—tsc --noEmitacross server + web. Run this after any change.npm --prefix server test— the server Jest suite (100% coverage gate in CI); the web side is typecheck-only.npm run watch— typecheck both sides in watch mode
The web dev server proxies /api to the server port, so always have the server running too.
Verification
Before committing or opening a PR, always run all checks and confirm they pass:
npm run typecheck— must exit 0; fix all errors before proceedingnpm run lint -- --max-warnings=2— must exit 0; fix errors (2 pre-existing warnings are OK)npm --prefix server test— must exit 0; fix any test failures before proceedingnpm run format:check— must exit 0; runnpm run formatto auto-fix then re-check
Do not open a PR if any command fails.
Demo mode — HANGAR_DEMO=1 npm run dev runs with a fictional board + seeded sessions and
no Jira. It's fully self-contained: config.ts synthesizes demoConfig() and never reads or
writes the real hangar.config.json/.env (saves are guarded). Implemented in
server/src/demo.ts (demo board, fake tickets, run seeds); seedDemoRuns() in sessions.ts
loads the seeds in-memory only (never persisted). Used for credential-free trials and screenshots.
Server architecture (server/src/)
index.ts— Express app and all routes (/api/*), including the SSE stream at/api/runs/:id/stream. Read endpoints (config/agents/skills/tickets) + write endpoints (config, Jira settings, runs, workflow runs).config.ts— loads/validates/saveshangar.config.json(path overridable viaCONFIG_PATH), resolves the repo root, reads/writes.env(Jira creds), exposesPORT. Config is held in memory and hot-swapped on save — no restart needed.types.ts— shared types.HangarConfig,BoardConfig,WorkflowConfig,Agent,Skill,Ticket, run/record shapes. Source of truth — start here when adding a field.jira.ts— Jira Cloud REST adapter (Basic auth: email + API token). One JQL per board.agents.ts/skills.ts— parse~/.claude/agents/*.mdand~/.claude/skills(plus repo skills) into the fleet shown in the assign menu.sessions.ts— the core: builds SDKquery()options, runs sessions in streaming-input mode, gates tools, injects per-run env, emits events to listeners. See "Run model" below.store.ts— persists each run/workflow as one JSON file under the data dir (.hangar/, overridable viaHANGAR_DATA_DIR) so transcripts/results survive restarts.worktree.ts— creates/removes a git worktree per run on ahangar/<label>-<id>branch.workflows.ts— runs a board's multi-step agent/skill pipelines.
Run model (the important part)
When a ticket is assigned an agent/skill, sessions.ts spawns a query():
- System prompt = the agent's
.mdbody; model from itsmodel:frontmatter. Skills run a generic session with~/.claudeloaded so the skill is available. - Working dir = the board's first
repoPath/repoPathsentry; the rest become the SDK'sadditionalDirectories(cross-repo access in one session). - Isolation (config
isolateRuns, default on): each run executes in its own git worktree + branch so parallel runs on one repo don't clobber each other. Non-git paths run in place. - Per-run env injected into every session so parallel Docker/compose stacks don't collide:
COMPOSE_PROJECT_NAME=hangar-<id>,HANGAR_RUN_ID,HANGAR_PORT_OFFSET. (These were renamed fromFLEETVIEW_*— keep theHANGAR_prefix.) - Permission mode (config
bypassPermissions, default true = unrestricted). When gated, reads/edits and read-only shell auto-run; mutating or unrecognized shell pauses for Allow/Deny. Tunable viaAUTO_ALLOW_TOOLS+isSafeBashCommandinsessions.ts(conservative:$(…), backticks,>redirection, or unknown command → gated). - Exclusive runtime (config
exclusiveAgents): names that boot Docker/bind fixed ports/use a shared tunnel run one at a time (others queue); code-only agents stay parallel. - Limits (config
maxTurnsdefault 300, optionalmaxBudgetUsd).
Runs emit each completed assistant message as a single assistant_text SSE event (whole message,
not token-by-token); includePartialMessages is not used. Individual tool calls are not rendered as
transcript lines and tool_use events carry only the tool name (no raw input) — the panel shows the
agent's messages plus a live rotating "working" status while tools run. Events are also persisted via store.ts.
Auth uses the host's existing Claude Code login / ANTHROPIC_API_KEY — Hangar does not manage
its own key.
Web (web/src/)
App.tsx— top-level board + topbar + view switching.api.ts— typed fetch wrappers for every/apiendpoint;types.tsmirrors server types.components/—Board,RunPanel(live SSE stream),SessionsView,Settings,SkillRunner,HandoffModal,NoteModal,WorkflowsBar,Markdown,Avatar.useTheme.ts,styles.css— styling. Icons come fromlucide-react.
Conventions & gotchas
- Match the existing style: 2-space indent, double quotes, terse explanatory comments that
state the why. Prettier and ESLint are configured (
.prettierrc.json,eslint.config.mjs) and run via husky on commit — let them reformat; don't fight them. - Naming: the product is Hangar. The old name was FleetView — do not reintroduce it.
The folder is
hangar/, config ishangar.config.json, data dir.hangar/, injected env isHANGAR_*, and worktree branches arehangar/…. - Adding a config field: use
/config-field— it enforces all five touch-points:HangarConfigtype,validateConfig/saveConfiginconfig.ts, the mirroredFullConfiginweb/src/types.ts, the Settings UI, andREADME.md. - Adding an API route: define it in
index.ts, add a typed wrapper inweb/src/api.ts, and keepweb/src/types.tsin sync withserver/src/types.ts. - Never commit
.env,hangar.config.json, or anything under.hangar/— all gitignored (secrets / personal board config / runtime data). Ship changes to the committed templates (.env.example,hangar.config.example.json) instead. - PR titles: plain sentence case, no type prefix. Write
Fix open-PR preference in dev-status, notbugfix: Fix open-PR preferenceorfeat/my-branch: Fix open-PR preference. - Docs live in
docs/— all documentation goes there, except thisCLAUDE.mdand the rootREADME.md. KeepREADME.mda lean overview that links intodocs/; don't add new standalone doc files to the repo root. - AI Workflow doc (required): whenever you change the AI Workflow connection — its routes, board
model, phases/skills, config shape, install flow, or card format — update
docs/AI_WORKFLOW.mdin the same change. Run/aiwf-syncafter any such change to verify the doc is in sync. - The server has a Jest suite (
npm --prefix server test); the web side has no tests yet — verify web changes withnpm run typecheckand, where it matters, by runningnpm run devand exercising the flow in the UI. Run/smokebefore merging any server change — it boots demo mode and exercises the critical API paths end-to-end. - Never bump
package.jsonversion in a feature branch. Version changes belong only inrelease/<version>branches created by the/releaseskill. Feature commits that touchpackage.jsonfor any other reason (deps, scripts) must leave the"version"field unchanged.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

