# blader/taskmaster architecture

> Architecture diagram of the GitHub repository blader/taskmaster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blader/taskmaster
- Repository: https://github.com/blader/taskmaster

## Overview

Taskmaster enforces explicit completion for coding-agent sessions. A session completes when the agent emits the session-specific done token; otherwise Taskmaster blocks stopping and requests more work. Codex enforcement continues the existing session through its wrapper and PTY bridge, while Claude enforcement uses a Stop hook. Both paths use the shared compliance prompt. The README documents these connections; source excerpts were unavailable, so the graph omits implementation details not established there.

Main entry points: [`hooks/inject-continue-codex.sh`](https://github.com/blader/taskmaster/blob/main/hooks/inject-continue-codex.sh) (Event monitor), [`hooks/check-completion.sh`](https://github.com/blader/taskmaster/blob/main/hooks/check-completion.sh) (Stop hook), [`run-taskmaster-codex.sh`](https://github.com/blader/taskmaster/blob/main/run-taskmaster-codex.sh) (Codex wrapper), [`hooks/run-codex-expect-bridge.exp`](https://github.com/blader/taskmaster/blob/main/hooks/run-codex-expect-bridge.exp) (Expect PTY bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_codex["Codex enforcement"]
  node_codex_wrapper["Codex wrapper"]
  node_codex_injector["Event monitor"]
  node_pty_bridge["Expect PTY bridge"]
end

subgraph group_claude["Claude enforcement"]
  node_claude_hook["Stop hook"]
  node_completion_check["Completion check"]
end

subgraph group_policy["Shared policy"]
  node_compliance_prompt["Compliance prompt"]
end

node_user(("User"))
node_codex_cli(("Codex CLI"))
node_session_logs["Codex session logs"]
node_claude_code(("Claude Code"))

node_user -->|"requests work"| node_codex_cli
node_codex_cli -->|"runs through"| node_codex_wrapper
node_codex_wrapper -->|"launches with logs"| node_codex_cli
node_codex_cli -->|"writes events"| node_session_logs
node_codex_injector -->|"watches events"| node_session_logs
node_codex_injector -->|"requests continuation"| node_pty_bridge
node_pty_bridge -->|"injects prompt"| node_codex_cli
node_codex_injector -->|"uses prompt"| node_compliance_prompt
node_user -->|"requests work"| node_claude_code
node_claude_code -->|"invokes on stop"| node_claude_hook
node_claude_hook -->|"runs check"| node_completion_check
node_completion_check -->|"uses prompt"| node_compliance_prompt
node_claude_hook -->|"blocks with feedback"| node_claude_code

click node_codex_wrapper "https://github.com/blader/taskmaster/blob/main/run-taskmaster-codex.sh"
click node_codex_injector "https://github.com/blader/taskmaster/blob/main/hooks/inject-continue-codex.sh"
click node_pty_bridge "https://github.com/blader/taskmaster/blob/main/hooks/run-codex-expect-bridge.exp"
click node_claude_hook "https://github.com/blader/taskmaster/blob/main/hooks/check-completion.sh"
click node_completion_check "https://github.com/blader/taskmaster/blob/main/check-completion.sh"
click node_compliance_prompt "https://github.com/blader/taskmaster/blob/main/taskmaster-compliance-prompt.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_codex_wrapper,node_codex_injector,node_pty_bridge,node_user toneBlue
class node_claude_hook,node_completion_check toneAmber
class node_compliance_prompt toneMint
class node_codex_cli,node_session_logs,node_claude_code toneIndigo
```

## Components

### Codex enforcement

- [Codex wrapper](https://github.com/blader/taskmaster/blob/main/run-taskmaster-codex.sh): `run-taskmaster-codex.sh`
- [Event monitor](https://github.com/blader/taskmaster/blob/main/hooks/inject-continue-codex.sh): `hooks/inject-continue-codex.sh`
- [Expect PTY bridge](https://github.com/blader/taskmaster/blob/main/hooks/run-codex-expect-bridge.exp): `hooks/run-codex-expect-bridge.exp`

### Claude enforcement

- [Stop hook](https://github.com/blader/taskmaster/blob/main/hooks/check-completion.sh): `hooks/check-completion.sh`
- [Completion check](https://github.com/blader/taskmaster/blob/main/check-completion.sh): `check-completion.sh`

### Shared policy

- [Compliance prompt](https://github.com/blader/taskmaster/blob/main/taskmaster-compliance-prompt.sh): `taskmaster-compliance-prompt.sh`

### Other components

- **User**
- **Codex CLI**
- **Codex session logs**
- **Claude Code**

## Connections

- User → Codex CLI: requests work
- Codex CLI → Codex wrapper: runs through
- Codex wrapper → Codex CLI: launches with logs
- Codex CLI → Codex session logs: writes events
- Event monitor → Codex session logs: watches events
- Event monitor → Expect PTY bridge: requests continuation
- Expect PTY bridge → Codex CLI: injects prompt
- Event monitor → Compliance prompt: uses prompt
- User → Claude Code: requests work
- Claude Code → Stop hook: invokes on stop
- Stop hook → Completion check: runs check
- Completion check → Compliance prompt: uses prompt
- Stop hook → Claude Code: blocks with feedback