ticket-master

A cross-platform, multi-provider workflow / operating mode for an AI coding agent.

ticket-master is a workflow/operating mode for an AI coding agent, not a tool that acts on its own. You keep one agent session ("Position 0") open in your terminal; whenever you notice a bug, a change request, or any project problem, you just type it in. Following this workflow, the agent captures it as a structured ticket, assigns it to the right project, scores it, and routes it — delegating to the best available AI provider/sub-agent for an immediate fix, or filing it into the project's own task management when delegation is not appropriate. Cross-platform (Windows/macOS/Linux), multi-provider (Claude Code, Codex, agy/Gemini).

🇩🇪 Deutsche Dokumentation → README_de.md

How It Works

ticket-master is a prompt-driven workflow: the agent reads the TICKET-MASTER prompt and follows it. Every step below is something the agent does by following the prompt — nothing runs on its own.

You report a bug or change request
        |
        v
[A] Intake — ticket file created, project assigned (GATE1)
        |
        v
[2-5] Characterise → Score → Match provider → Rank 3 candidates (GATE2)
        |
        v
[B] Delegate to best available provider (GATE4 success check + fallback chain)
        |
   or   v
[C] Write to project task management (usage limit / all unavailable)
        |
        v
Position 0 — waiting for next ticket

graph TD
    User([User reports bug / change request]) --> Position0[Triage Console: Position 0]
    Position0 --> GATE1{GATE 1: Intake}
    GATE1 -->|Create Ticket File| TxtFile[tickets/T-YYYYMMDD-NN.txt]
    TxtFile --> GATE2{GATE 2: Characterise & Score}
    GATE2 -->|Calculate Score| Score[Score = 10-Clarity + Complexity + Creativity + Context + Criticality]
    Score --> Router{Router Decision}
    
    Router -->|Tier 1-4 & Urgent| GATE4{GATE 4: Delegate}
    Router -->|Backlog/Low Urgency| TaskDB[Project Task Board<br>tickets/PENDING/]
    Router -->|Manual Handoff| UserHandoff[User Intervention<br>tickets/.USER/]
    
    GATE4 -->|Success| Solved[tickets/SOLVED/<br>Commit & Verify]
    GATE4 -->|Fail / Timeout| Fallback[Fallback Chain<br>Next Best Provider]
    Fallback --> GATE4

Key design principles (how the agent is instructed to behave):

Lean Router: The agent in this mode stays lean. Execution is delegated to sub-agents that report back compactly (commit hash + one line).
Companion Pattern: For a series of tickets in the same domain, one companion sub-agent is spawned and reused — paying orientation cost once, not per ticket.
Score-Based Routing: The agent scores every ticket on five dimensions (Clarity, Complexity, Creativity, Context, Criticality) to determine the required provider tier.
Graceful Fallback: If the preferred provider is unavailable, the prompt's fallback chain and checkpoint ensure tickets are never dropped.
Provider-Agnostic: Works with any CLI-based LLM provider. The prompt and config ship with support for Claude, Codex, and agy (Gemini). Extend via config.
Cloud-Ready / Multi-System: The ticket queue works across multiple machines sharing a cloud-synced folder (OneDrive, Dropbox, Google Drive). Claims are signalled via filename rename — atomic on NTFS, no lock files needed.

Quick Start

# 1. Clone the repository
git clone https://github.com/dev-bricks/ticket-master.git
cd ticket-master

# 2. Copy and edit the config
cp config/ticket-master.config.example.json config/ticket-master.config.json
# -> Edit config/ticket-master.config.json:
#    - Add your project directories to project_roots[]
#    - Verify provider commands match your installed CLIs

# 3. Launch (default: Claude)
./bin/ticket-master.sh               # Unix/macOS
.\bin\ticket-master.bat              # Windows CMD
.\bin\ticket-master.ps1              # Windows PowerShell

This launches your chosen CLI provider with the TICKET-MASTER prompt for the selected language (prompts/TICKET-MASTER.<lang>.md, default English). The agent reads the prompt, orients itself on your projects, and goes to Position 0 — waiting silently for your first ticket.

Prompt Language

The agent prompt ships in two fully equivalent versions:

prompts/TICKET-MASTER.en.md (English, default)
prompts/TICKET-MASTER.de.md (German)

Select the language with the TM_LANG environment variable; the starters load prompts/TICKET-MASTER.${TM_LANG}.md and fall back to English with a warning if the requested file is missing. The config field default_language documents the intended default.

TM_LANG=de ./bin/ticket-master.sh        # German prompt
TM_LANG=en ./bin/ticket-master.sh        # English prompt (default)

$env:TM_LANG = "de"; .\bin\ticket-master.ps1

Starter Matrix

OS	Provider	Command
Unix / macOS	Claude	`./bin/start-claude.sh` or `./bin/ticket-master.sh --provider claude`
Unix / macOS	Codex	`./bin/start-codex.sh` or `./bin/ticket-master.sh --provider codex`
Unix / macOS	agy (Gemini)	`./bin/start-agy.sh` or `./bin/ticket-master.sh --provider agy`
Windows CMD	Claude	`bin\start-claude.bat` or `bin\ticket-master.bat --provider claude`
Windows CMD	Codex	`bin\start-codex.bat` or `bin\ticket-master.bat --provider codex`
Windows CMD	agy (Gemini)	`bin\start-agy.bat` or `bin\ticket-master.bat --provider agy`
Windows PowerShell	Claude	`.\bin\ticket-master.ps1 -Provider claude`
Windows PowerShell	Codex	`.\bin\ticket-master.ps1 -Provider codex`
Windows PowerShell	agy (Gemini)	`.\bin\ticket-master.ps1 -Provider agy`

Environment Variables

Variable	Default	Effect
`TM_PROVIDER`	`claude`	Override provider without a flag
`TM_LANG`	`en`	Prompt language; loads `prompts/TICKET-MASTER.${TM_LANG}.md` (falls back to `en`)
`TM_SKIP_PERMISSIONS`	`0`	Set to `1` to pass `--dangerously-skip-permissions` to Claude

Configuration

Copy config/ticket-master.config.example.json to config/ticket-master.config.json (the real config is gitignored).

Key Fields

Field	Description
`tickets_dir`	Where ticket files live (default: `./tickets`)
`prompts_dir`	Reserved. The `bin/` launchers currently resolve prompts from the repo's own `prompts/` folder; changing this field has no effect yet
`default_language`	Documented default prompt language (`en`/`de`); runtime override via `TM_LANG`
`project_roots[]`	Your projects — add name, path, pipeline for each
`providers.claude`	Claude CLI config (`command`, `default_model`, `args`)
`providers.codex`	Codex CLI config
`providers.agy`	Gemini CLI config
`default_provider`	Provider used when none is specified
`advisor.enabled`	Enable advisor model for high-stakes tickets (score ≥ 35)
`advisor.threshold_score`	Score at which advisor is recommended
`score_thresholds`	Tier boundary scores (tier1_max, tier2_max, etc.) — fallback only, see `router_command`
`router_command`	Optional external multi-model/task router; consulted before the score-fallback formula
`task_db_command`	Optional "later" sink for `woche`/`backlog`-urgency tickets

Example `project_roots` Entry

{
  "name": "my-app",
  "path": "/home/user/projects/my-app",
  "pipeline": "software"
}

Discovery Context

Use the canonical name dev-bricks/ticket-master when searching for this project. The repository is about LLM ticket routing: a prompt-driven triage console that helps one coding-agent session capture bugs, score them, select a Claude/Codex/agy provider, and keep an auditable ticket trail.

Good search phrases:

dev-bricks ticket-master
LLM ticket router agent
AI coding agent triage console
Claude Codex Gemini ticket routing
multi-provider LLM task router
prompt-driven issue intake workflow
companion pattern AI agent workflow

Not this project: Ticketmaster event APIs, concert ticket bots, help-desk SaaS, customer support ticketing, marketplace ticket resale, or a standalone bug tracker that files issues without an active LLM agent session.

How Routing Works

Score Formula

SCORE = (10 - CLARITY) + COMPLEXITY + CREATIVITY + CONTEXT + CRITICALITY

Each dimension is 0–10. Total range: 0–50.

Score Range	Tier	Typical Use
0–8	Tier 1	Fast / cheap — boilerplate, formatting, trivial fixes
9–12	Tier 2	Capable chat — standard bugs, documentation
13–28	Tier 3	Capable coder / researcher — complex bugs, code review
29–50	Tier 4	Architect / reviewer — design, proofs, high-stakes changes

At score ≥ 35, an advisor model is recommended.

Directory Layout

tickets/
├── _logs/                      <- DEPRECATED shared intake log (pre-1.5.0)
│   └── INTAKE-TRIAGE-LOG.txt
├── _templates/TICKET.txt       <- ticket template
├── *.txt                       <- open tickets (one .txt file each)
├── QUEUED/                     <- handed to a provider, awaiting result
├── PENDING/                    <- moved to project task management
├── .USER/                      <- requires user-launched model / manual step
└── SOLVED/                     <- resolved and empirically confirmed

The audit/triage trail lives per ticket in the ticket file itself (STATUS / LOG / SOLUTION fields). Trivial tickets that are resolved and verified immediately get a minimal ticket file dropped directly into tickets/SOLVED/. The former shared tickets/_logs/INTAKE-TRIAGE-LOG.txt is deprecated: with several machines appending to one cloud-synced file, sync conflict copies ate log lines.

Cloud-Ready: Multi-System Claim Convention

When the tickets/ directory lives in a cloud-synced folder shared across multiple machines, claims are signalled via the filename — no in-file fields or lock files needed:

State	Filename pattern	Example
Unclaimed	`T-YYYYMMDD-NN.txt`	`T-20260619-01.txt`
Claimed	`T-YYYYMMDD-NN.<HOST>.txt`	`T-20260619-01.WORKSTATION.txt`
Solved	move to `SOLVED/`	as usual

Glob patterns: tickets/T-??????-??.txt (unclaimed) · tickets/T-*.LAPTOP.txt (mine).

A rename within the same directory is atomic on NTFS and most cloud sync implementations. If a conflict copy appears, one system has won the claim; the other rolls back and picks the next unclaimed ticket.

Companion Pattern

For a series of related tickets, the master spawns one companion sub-agent and reuses it via SendMessage. The companion orients itself once (reads project files, learns conventions) and then processes subsequent tickets without re-paying that cost. The master rotates the companion when the domain changes significantly or when its context grows large.

Fallback Chain

Candidate 1
    | fail
    v
Candidate 2
    | fail
    v
Candidate 3
    | fail
    v
CHECKPOINT ALPHA:
    1. Async delegation (sync folder / cron)
    2. Project task management (-> PENDING)
    3. User handoff (-> .USER)

Personal-Assistant Expansion (optional): Domain Map, Urgency & Delegation

Three optional layers turn the plain ticket router into a small personal- assistant triage console, on top of a BACH-style personal-assistant install:

Domain map (1.6.0, extended 1.8.0): lib/domains_generator.py generates config/domains.json — a domain → expert map, cross-referenced against a skill registry to flag which experts already exist as standalone skills. It only needs BACH at generation time; config/domains.json itself is a plain, BACH-free JSON file at runtime. experts[] is provenance/grouping metadata only — the prompt routes directly to the resolved skill(s), never to the expert as an intermediate hop. Since 1.8.0, a stage-2 fuzzy pass (fuzzy_match_skills(), plus an optional --extra-skills-dir second skill inventory) additionally recognizes experts that govern a whole skill FAMILY ("status": "teilportiert", "matched_skills": a list) rather than a single 1:1 ported skill. See config/domains.example.json for the schema.
Urgency axis (1.7.0): config/urgency.json (schema: config/urgency.example.json) maps each domain to a default deadline (sofort / heute / woche / backlog) plus escalation rules (e.g. published software + a severe bug escalates to sofort, dispatching a diagnosis-only sub-agent first when severity is unclear). This axis is decoupled from the 5-dimension complexity score — a ticket can be low-complexity and urgent, or high-complexity and not urgent. Borderline calls can optionally consult a configured preference hint (preference_model_hint.command); low confidence always means asking the user instead of guessing.
Delegation wiring (1.7.0, extended 1.8.0): the prompt's intake gate resolves an ENDPOINT for a matched domain (via domains.json, then optional skill-registry tools, then a GAP flag instead of a silent fallback); model selection prefers an optional external router_command over the built-in score-formula fallback; a permission check against LOCK*.txt / LOCK.permissions.json-style conventions runs before every worker spawn; and woche/backlog-urgency tickets are handed to an optional task_db_command "later" sink instead of spawning a sub-agent. Since 1.8.0, a "teilportiert" domain match equips the worker with all skills in matched_skills, not just the first — an expert can govern a whole skill family (see the domain map section above).
System-knowledge layer (1.9.0): config/knowledge.json (schema: config/knowledge.example.json) lists knowledge sources in four categories — maps (structural, loaded at boot), state (changes during the session, re-checked before every routing decision), capabilities (consulted at endpoint/model lookup), and user_model (a preference hint, consulted only on genuine borderline calls). Ground rule: trust generated maps over memory — on a conflict, regenerate the map rather than trusting what you recall.

See CHANGELOG.md (1.6.0–1.9.0) for details.

Requirements

A CLI-based LLM provider (at least one of: claude, codex, agy)
Python 3.10+ (for tests only; the router itself runs inside the LLM session)
No additional Python dependencies

Provider Installation

Provider	Install
Claude CLI	`npm install -g @anthropic-ai/claude-code`
Codex CLI	`npm install -g @openai/codex`
agy (Gemini)	See antigravity docs

Running the Smoke Tests

python tests/test_smoke.py

Checks: directory structure complete, config JSON valid, prompt contains no forbidden absolute paths or system-specific terms.

Part of the ellmos stack family

ticket-master is deliberately both: a standalone dev tool and a core module of the ellmos stack family.

Core module of ellmos-ai/agent-ops-stack (role ticket-routing); family/catalog: ellmos-ai/stacks; org overview: ellmos-ai.

License

Author

Lukas Geiger (github.com/lukisch)

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
assets		assets
bin		bin
config		config
lib		lib
prompts		prompts
tests		tests
tickets		tickets
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README_de.md		README_de.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
TODO.md		TODO.md
VERSION		VERSION
ellmos-module.v2.json		ellmos-module.v2.json
llms.txt		llms.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

ticket-master

How It Works

Quick Start

Prompt Language

Starter Matrix

Environment Variables

Configuration

Key Fields

Example `project_roots` Entry

Discovery Context

How Routing Works

Score Formula

Directory Layout

Cloud-Ready: Multi-System Claim Convention

Companion Pattern

Fallback Chain

Personal-Assistant Expansion (optional): Domain Map, Urgency & Delegation

Requirements

Provider Installation

Running the Smoke Tests

Part of the ellmos stack family

License

Author

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ticket-master

How It Works

Quick Start

Prompt Language

Starter Matrix

Environment Variables

Configuration

Key Fields

Example project_roots Entry

Discovery Context

How Routing Works

Score Formula

Directory Layout

Cloud-Ready: Multi-System Claim Convention

Companion Pattern

Fallback Chain

Personal-Assistant Expansion (optional): Domain Map, Urgency & Delegation

Requirements

Provider Installation

Running the Smoke Tests

Part of the ellmos stack family

License

Author

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Example `project_roots` Entry