Trekker

Trekker

Overview

Use Trekker as the persistent source of truth for tracked work. update_plan is optional session scaffolding only; long-lived tasks, progress notes, dependencies, and handoff context belong in Trekker.

Run trekker quickstart whenever command syntax is unclear. In Codex, use the trekker CLI directly. Do not assume Claude Code slash commands, MCP tools, or lifecycle hooks exist.

Quick Reference

Workflow

Use this cycle whenever Codex is managing tracked work with Trekker:

flowchart TD
    A["Session starts or user asks for tracked work"] --> B["Confirm `.trekker` state"]
    B --> C["Search first with `trekker search`"]
    C --> D{"Existing task fits?"}
    D -->|Yes| E["Read task, comments, history, and deps"]
    D -->|No| F["Create task or epic with clear description"]
    E --> G["Set task to `in_progress`"]
    F --> G
    G --> H["Do the work"]
    H --> I{"Need to pause or switch context?"}
    I -->|Yes| J["Add `Checkpoint:` comment"]
    J --> C
    I -->|No| K{"Work complete?"}
    K -->|No| H
    K -->|Yes| L["Add `Summary:` comment"]
    L --> M["Mark task `completed`"]
    M --> N["Run `trekker ready`"]
    N --> C

1. Confirm project state. If .trekker already exists, use it. If the user wants tracking and Trekker is not initialized, ask before running trekker init because it changes project state.

2. Search first, always. Before creating, starting, or revisiting work, run trekker search with one distinctive keyword at a time. Trekker uses FTS5, so multi-word queries narrow results with AND logic.

3. Restore context before changing anything. For an existing task, inspect trekker task show, trekker comment list, trekker history --entity, and trekker dep list. Prefer continuing or updating related tasks instead of creating duplicates.

4. Track execution in Trekker. Set a task to in_progress before doing the work. Keep one task in_progress when practical. Add progress or checkpoint comments for discoveries, partial work, blockers, and context that a later session would need.

5. Track new work with enough detail. For non-trivial work, create tasks with specific titles and descriptions that name the files, modules, or acceptance criteria involved. For larger features, create an epic and wire task order with dependencies.

6. Close work cleanly. Before marking a task completed, add a Summary: comment covering what changed, key decisions, and files touched. After completion, run trekker ready to surface the next unblocked task.

Example

trekker search "auth"
trekker task show TREK-12
trekker comment list TREK-12
trekker history --entity TREK-12
trekker task update TREK-12 -s in_progress
trekker comment add TREK-12 -a "codex" -c "Checkpoint: verified middleware gap in src/auth.ts. Next: patch token refresh path."
trekker comment add TREK-12 -a "codex" -c "Summary: fixed refresh-token validation in src/auth.ts and src/session.ts. Added expiry guard and removed duplicate branch."
trekker task update TREK-12 -s completed
trekker ready

Common Mistakes

• Treating update_plan as the system of record. It does not survive sessions; Trekker does.
• Creating a new task before searching for an existing one to extend.
• Marking a task complete without a summary comment.
• Using Claude plugin concepts such as /trekker:start or hooks. In Codex, use direct CLI commands only.
• Writing vague task titles or descriptions that future agents cannot act on.

Red Flags

• "I only need local notes for this."
• "This is obvious enough that I can skip comments."
• "I will summarize after I mark it completed."
• "I can create a fresh task faster than searching."

If one of those thoughts appears, stop and use Trekker properly before continuing.