From the Inside Claude Code: The Claude Code Ecosystem architecture map
Claude jobs reach GitHub only through a read-only wrapper and event-bound writes
strength · medium · verified
scripts/gh.sh allows only issue view, issue list, search issues and label list, rejects repo:, org: and user: qualifiers, and requires numeric issue numbers. Writes go through edit-issue-labels.sh and comment-on-duplicates.sh, which read the issue number from GITHUB_EVENT_PATH, drop unknown labels and cap duplicates at three existing issues. Write, Edit, WebFetch and WebSearch are disallowed and the runner egress is allow-listed.
Impact: A prompt-injected agent cannot touch other issues, other repositories, code, or arbitrary hosts.
CLAUDE_CODE_SCRIPT_CAPS further limits triage to two label edits and dedupe to one duplicate comment per run.
The trail
Open on the mapMore from this board
- Session Store is a single point of failure for 7 modules, from the clients to the package exports
- Optional SessionStore methods raise instead of being absent, so a change in Types reaches 13 modules
- Every defence against hidden instructions rests on one small sanitizer
- Interrupt and other control calls stall when nobody is reading messages
- Day 1: start with marketplace.json, the contract everything else serves
- Day 2: follow the install path from Claude Code into one plugin
- Session Store is shared by three groups of code, so a change to it reaches all of them
- Every SDK module imports its exceptions from one file, _errors.py
- can_use_tool is a ready gate seam with subagent provenance
- PR-controlled agent config is restored from the base branch before Claude starts
- Start with the gate order in the Run Orchestrator
- Then follow untrusted text from GitHub into the prompt
- The action and the base action share an untyped prompt-file contract
- The transport is the only translator from options to Claude Code CLI flags
- Both public entry points share one control-protocol engine
- Learn issue automation as one loop from GitHub event back to GitHub
- The gh.sh wrapper is the safety contract both Claude jobs rest on
- The triage and dedupe agents are boxed in identity, tools and network
- Day 3: the chat-channel flow shows the only long-running code
- Day 4: CI keeps the catalogue honest and current
- Public API code reaches straight into Session Store instead of going through a session entry point
- A failed SessionStore append is retried, then dropped; mirror_error is the only signal
- Channel messages carry sender identity, giving the session provenance
- CI already gates external plugins with an agent and reverts on failure
- Sessions copies the CLI's folder-naming hash, and 6 modules depend on that copy
- Spend and run length are bounded at the transport
- Tag mode gives Claude a narrow, workspace-bound tool list
- Skip post-run reporting and branch plumbing at first
- Command-line construction is hardened against argument injection
- Tool permission requests fail closed
- Skip the engine, mods and examples when the goal is issue automation
- Lifecycle timeouts are restated outside their single source of truth
- The duplicate comment script is pinned to the upstream repository
- Every agent-driven closure has a human override before it happens
- Skip for now: config-only integrations, CI plumbing and single-file plugins
- Key vocabulary: marketplace entry, plugin, channel, pairing, permission relay, SHA bump
- Plugins are fully independent and deploy on their own
- External-PR workflows never execute contributor code
- Channel servers keep bot tokens owner-only and refuse injected pairing requests