td CLI

repository·main·Indexed 42 days ago

https://github.com/marcus/td

A minimalist CLI for tracking tasks and managing state across AI-assisted coding sessions. It serves as an 'external memory' for AI agents, providing structured handoffs, context summaries via `td usage`, and task workflow guidance through the `td-task-management` skill to prevent progress loss during context window resets.

Tokens
129.4K
Snippets
389
Records
603
Agent score
52%

What's inside td

  1. Project Structure of the Docs Site

    main

    The documentation site is built with Docusaurus and follows this directory structure:

    • website/docs/: Markdown files for documentation.
    • website/src/pages/: Custom pages (e.g., index.js for the landing page).
    • website/src/css/: Custom stylesheets (e.g., custom.css).
    • website/static/img/: Images and assets (e.g., td-logo.png).
    • website/static/.nojekyll: Prevents Jekyll processing on GitHub Pages.
    • website/docusaurus.config.js: Main site configuration.
    • website/sidebars.js: Defines the documentation sidebar structure.
    • website/package.json: Project dependencies.
  2. Architecture Overview of td

    main

    td is a Go-based task management CLI built with Cobra and backed by SQLite. Its architecture is divided into several specialized packages:

    • cmd/: Contains 67 Cobra CLI commands (e.g., create, start, log, handoff, review, approve).
    • internal/db/: Handles SQLite persistence, including 29 migrations, CRUD operations, and logged mutations.
    • internal/models/: Defines core domain types like Issue, Log, Handoff, Board, WorkSession, and Note.
    • internal/session/: Manages session IDs scoped by branch and agent.
    • internal/query/: Implements the TDQ query language (lexer, parser, AST, evaluator).
    • internal/sync/: Manages the event-based sync protocol (push/pull, conflict resolution).
    • internal/workflow/: A state machine that enforces transitions and guards.
    • internal/serve/: Provides an HTTP API server with SSE streaming.
    • internal/api/: The sync server handling multi-project auth and rate limiting.
    • internal/events/: Defines the event taxonomy for entity/action normalization.
    • pkg/monitor/: A Bubble Tea TUI dashboard with a modal system.
  3. td Feature Tiers and Pricing Model

    main

    The td project follows an open-core model with different feature sets available across four tiers. Pricing is based on per-user (per-seat) billing, where one seat represents one human user (allowing unlimited AI agents under that user's session).

    | Tier | Price | Includes |
    |---|---|---|
    | **Free** | $0 | 1 project, 3 members, self-hosted sync only |
    | **Pro** | ~$8-12/user/month | Managed hosting, unlimited projects, E2E encryption, priority support |
    | **Team** | ~$15-20/user/month | Pro + integrations, webhooks, analytics dashboard, granular permissions |
    | **Enterprise** | Custom | Team + SSO/SAML, SCIM, audit logs, web view, data residency, SLA |
  4. Explore the td ecosystem and integrations

    main

    The td ecosystem includes several tools built on top of it to enhance the developer experience:

    • Sidecar: A terminal development dashboard that embeds td monitor alongside git diffs and file browsing.
    • td-gui: A local web UI for viewing issue details, structured handoffs, review dialogs, and swimlane boards.
    • myrlin-workbook: A browser-based session manager that surfaces td issues in sidebars and promotes them to agent sessions.
    • sergeant: A multi-agent coordination CLI with deep td integration for routing findings and managing review gates.
    • pi-td: An extension for the Pi coding agent harness providing native td tools.
    • llm-agents.nix: Nix packages and Flakes for integrating td into the LLM agent ecosystem.
  5. How boards work

    main

    Boards are dynamic, saved views of your issues defined by a query. They do not 'contain' issues; instead, they filter them based on criteria. You can also manually position issues within a board for priority ordering.

    td board create "Sprint 1" --query "priority <= P1"
    td board create "Bug Triage" --query "type = bug AND status = open"
  6. Use the Pointer Pattern for model-stored inputs

    main

    When storing inputs (like textinput.Model or textarea.Model) as fields in a Bubbletea Model struct, you must store them as pointers (e.g., *textinput.Model).

    The Problem: Bubbletea copies the Model (value receiver) on every Update call. If you store the input as a value, the modal captures a pointer to a field in a specific copy of the model. When Bubbletea creates a new copy during the next Update, the modal's pointer will point to stale data in the old copy.

    The Solution: By storing pointers, Bubbletea copies the pointer itself, ensuring the modal and all subsequent Model copies reference the same underlying data instance. This allows the modal to update the shared input automatically via modal.HandleKey() without manual synchronization.

    type Model struct {
        nameInput  *textinput.Model   // pointer, not value
        queryInput *textarea.Model    // pointer, not value
        myModal    *modal.Modal
    }
    
    func (m Model) openModal() Model {
        // Allocate on heap, store pointer
        ti := textinput.New()
        ti.Placeholder = "Name..."
        ti.Focus()
        m.nameInput = &ti
    
        ta := textarea.New()
        ta.SetWidth(40)
        ta.SetHeight(3)
        m.queryInput = &ta
    
        // Pass pointer directly (no & needed — already a pointer)
        m.myModal = modal.New("Edit",
            modal.WithPrimaryAction("save"),
        )
        m.myModal.AddSection(modal.InputWithLabel("name", "Name:", m.nameInput))
        m.myModal.AddSection(modal.TextareaWithLabel("query", "Query:", m.queryInput, 3))
        m.myModal.Reset()
        return m
    }
    
    // In Update: just delegate to modal.HandleKey() — no manual forwarding needed.
    action, cmd := m.myModal.HandleKey(msg)
  7. How td resolves the base directory for .todos

    main

    The workdir.ResolveBaseDir logic ensures that td can find the shared .todos database even when working from external git worktrees. It resolves the base directory by checking in this order:

    1. The current path.
    2. The git top-level directory.
    3. Known associations.
    4. The main worktree.

    This allows multiple worktrees to share a single source of truth for issues and session history.

  8. Best Practices for AI Agents using td

    main

    When using td in an AI-assisted development environment, follow these patterns to maintain high-quality context and continuity:

    • New Sessions: Start a fresh context with td usage --new-session -q to see current focus and pending work without verbose output.
    • Contextual Logging: Always use --decision and --uncertain flags when logging to aid future sessions in understanding the 'why' behind implementation choices.
    • Handoffs: Use td handoff to explicitly capture what is done and what remains when a session ends.
    • Work Sessions: Group related issues using td ws to simplify tracking and handoffs.
    • File Tracking: Use td link to associate files with issues, helping future sessions understand what code was modified.
    • Efficiency: If blocked, do not waste tokens retrying; check td next or td list --status open to switch tasks.
    • Verifiable Reviews: For independent verification, give reviewing sub-agents their own TD_CONTEXT_ID. In trusted mode, use --reviewed-by "<who>" or --self-review --reason "..." to maintain an honest audit trail.
  9. Understand the td-sync architecture

    main

    The td-sync system enables bidirectional event-based replication between td clients and a central td-sync server.

    Architecture Model:

    • Client: A td client using a local SQLite database and the sync library.
    • Server: A td-sync server (Go binary) that manages users, API keys, and project memberships in server.db, and maintains an append-only event log for each project in /data/projects/{id}/events.db.
    • Communication: Clients push and pull events over HTTPS.

    Key Components:

    • internal/sync/: The core shared library for both client and server (event application, backfill, push/pull logic).
    • internal/syncclient/: The HTTP client used by the td CLI to interact with the sync API.
    • cmd/td-sync/: The entry point for the server binary.
    • cmd/autosync.go: The client-side logic for automatic synchronization (startup, debounce, and periodic intervals).
    td client (SQLite + sync lib)  ──HTTPS──▶  td-sync server (Go binary)
                                                  ├─ server.db (users, keys, projects, members)
                                                  └─ /data/projects/{id}/events.db (append-only event log)
  10. How the declarative modal library works

    main

    The library uses a render-then-measure pattern to solve the problem of accurately tracking hit regions for mouse support in TUIs. This approach eliminates off-by-one errors and duplicated position calculations that occur when calculating positions inline during rendering.

    The Lifecycle:

    1. Render Phase: Sections render content and report focusable elements with relative offsets.
    2. Layout Phase: The library measures the actual rendered heights of the sections.
    3. Registration Phase: Hit regions are registered at absolute positions based on those measurements.

    This pattern enables automatic keyboard navigation (Tab/Shift+Tab to cycle, Enter to activate, Esc to cancel) and automatic hover management via mouse motion.

  11. Command Groups in td

    main

    Commands in td are organized into functional groups. This categorization helps in structuring the CLI and applying consistent behaviors.

    GroupIDPurposeExamples
    coreCRUD operationscreate, list, show, update, delete
    workflowIssue lifecyclestart, review, approve, handoff
    queryData analysistree, dependencies, critical-path
    shortcutsFiltered listsready, next, blocked, in-review
    sessionSession managementstatus, usage, focus, ws
    filesFile linkinglink, unlink, files
    systemToolingversion, info, export, import
  12. Distinguishing between Skills and Project Documentation

    main

    The td project separates guidance into two distinct types to optimize for AI-assisted development:

    1. Skills (td-task-management/): These contain task workflow guidance. They are designed to be consumed by AI agents to manage the lifecycle of tasks (e.g., start, log, handoff, review).
    2. Project Documentation (docs/): This contains project-specific architecture and design docs. These are intended for understanding the codebase, implementation details, and technical specifications.