🚀 Tracket

Bridging the Gap Between AI Coding Agents and Humans.

Tracket is a session-based continuity system designed for high-velocity AI-human collaboration. It eliminates "context drift" and slashes token usage by providing a Git-backed, Markdown-native state layer that both humans and AI agents can understand.

---

🌟 Why Tracket?

Working with AI agents (like Claude Code, Gemini CLI, or Aider) on large projects often leads to two problems:

1. Token Bloat: Feeding the agent the entire project history every session is expensive and slow.
2. The "Black Box" Problem: Humans often lose track of exactly what an agent changed, what bugs it found, and what it planned to do next.

Tracket solves this with a "Pulse & Record" loop.

---

✨ Key Features

• 🧩 Hybrid Context Strategy: Use the pulse command to give AI agents a compressed summary (< 500 tokens) instead of thousands of lines of history.
• 📊 Vibrant Dashboard: A high-fidelity, glassmorphic React dashboard to visualize roadmap progress, milestones, and project health.
• 📄 Markdown-Native: No database required. All state lives in .tracket/ as human-readable Markdown files.
• 🤖 Agent Handoffs: Automatically generate "Next Steps" for the next agent session, ensuring seamless continuity.
• 🛠️ Interactive Init: Tell the AI your vision, and let it propose a structured roadmap for your approval.
• 🤖 Gemini CLI Automation: Run /tracket -new to have the agent handle the entire setup, dependency installation, and dashboard launch automatically.
• 🔌 Universal Agent Support: Native integration for Claude Code, Cursor, Windsurf, and Aider via rule files and MCP (Model Context Protocol).

---

🤖 Multi-Agent Support

Tracket is built to work with every popular AI coding assistant.

1. Claude Code

Tracket includes a CLAUDE.md file that automatically instructs Claude Code to use the pulse and record commands. No setup required!

2. Cursor & Windsurf

The .cursorrules file ensures that IDE-based agents respect the Tracket continuity protocol.

3. MCP Server (For Claude Desktop, Windsurf, etc.)

Tracket implements the Model Context Protocol. This allows agents to use Tracket tools natively without running shell commands.

To use MCP: Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "tracket": {
      "command": "npx",
      "args": ["-y", "tsx", "C:/path/to/tracket/src/mcp/index.ts"]
    }
  }
}

4. Aider

Follow the instructions in .tracket/rules/aider-instructions.md.

---

🤖 Gemini CLI Integration

If you use Gemini CLI, you can automate the entire Tracket lifecycle.

Setup the Command

Run the provided installer script to add the /tracket command to your CLI:

.\install-gemini-integration.ps1

Usage

Once installed, you can just say:

• /tracket -new : The agent will walk you through creating a project and automatically pop up the UI.
• /tracket record : The agent will help you log your session.
• /tracket pulse : Get the instant context.

---

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/gsl0001/tracket.git
cd tracket

# Install all dependencies (Core + Dashboard)
npm install

2. Initialize Your Project

Set up your roadmap and project vision in one command:

npx tsx src/cli/index.ts init "My Project" --vision "A smart task manager with AI features"

3. Start the Visual Dashboard

Open two terminals:

Terminal 1 (Data API):

npm run api

Terminal 2 (React UI):

npm run dashboard

Visit http://localhost:3000 to see your vibrant cockpit.

---

🔄 The AI-Human Loop

Step 1: Provide the Pulse

At the start of an AI agent session, run:

npx tsx src/cli/index.ts pulse

This gives the agent the project name, current completion %, and a link to the last handover file.

Step 2: Agent Works

The agent performs its tasks (coding, debugging, etc.).

Step 3: Record the Session

When the agent is done, it records its progress:

npx tsx src/cli/index.ts record "Implemented User Auth" \
  -c "Added login logic" "Setup JWT middleware" \
  -n "Build the user profile page" \
  -p "25%"

This updates the master.md and creates a timestamped log in .tracket/sessions/.

---

📂 Architecture

Tracket uses a flat-file "database" for maximum transparency and Git compatibility.

.tracket/
├── master.md          # Global state (YAML + Roadmap)
└── sessions/          # Historical logs
    └── 2026-04-12-session.md

• Master File: The "Source of Truth."
• Session Logs: The historical record.
• Sidecar API: A lightweight Express server that watches these files and feeds the Dashboard.

---

🤖 Integrating with AI Agents

To maximize efficiency, add this to your CLAUDE.md or system prompt:

"Always start by running npx tsx src/cli/index.ts pulse to get the current project state. At the end of your work, run the record command to log your changes and set instructions for the next session."

---

🤝 Contributing

Contributions are welcome! Whether it's a new visual component for the dashboard or an improvement to the CLI, feel free to open a PR.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/vibrant-ui)
3. Commit your changes (git commit -m 'Add glow effect to progress bars')
4. Push to the branch (git push origin feature/vibrant-ui)
5. Open a Pull Request

---

📜 License

Distributed under the ISC License. See LICENSE for more information.

---

Built with ❤️ by gsl0001

---

📊 Repository Status

• Current Version: v1.0.0-prototype
• Last Updated: 2026-04-12
• Main Branch: master
• Latest Commit: 38969a8