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

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`	Where prompt files live (default: `./prompts`)
`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.)

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/                      <- audit trail (separate from ticket queue)
│   └── 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

Trivial tickets that are resolved immediately do not need a .txt file — a single line in tickets/_logs/INTAKE-TRIAGE-LOG.txt suffices.

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)

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.

License

Author

Lukas Geiger (github.com/lukisch)

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
assets		assets
bin		bin
config		config
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
llms.txt		llms.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Requirements

Provider Installation

Running the Smoke Tests

License

Author

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

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

Requirements

Provider Installation

Running the Smoke Tests

License

Author

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Example `project_roots` Entry

Packages