Tocket

The Context Engineering Framework for Multi-Agent Workspaces

AI agents forget everything between sessions. When multiple agents work on the same codebase, they re-read files, duplicate work, and make conflicting decisions. Tocket fixes this with shared context files that any agent can read — no vendor lock-in, no special integrations.

The idea in 30 seconds

Tocket is a file convention. It adds a .context/ directory to your repo with markdown files that describe your project's current state, architecture, and progress. Any AI agent that can read files — Claude, Gemini, GPT, Cursor, Copilot — can pick up where the last session left off.

your-project/
  .context/
    activeContext.md      # What's happening right now
    systemPatterns.md     # How the codebase is organized
    techContext.md        # Stack and build tools
    productContext.md     # What the product is and why
    progress.md           # What's done, what's next
  TOCKET.md               # Protocol rules (agent-agnostic)
  CLAUDE.md               # Executor instructions (auto-detected per agent)
  GEMINI.md               # Architect instructions (auto-detected per agent)

All files are plain markdown, committed to git, and readable by any tool.

You don't need the CLI

The protocol is just files. You can adopt it manually:

1. Create a .context/ directory with activeContext.md and systemPatterns.md
2. Add a TOCKET.md to your repo root
3. Tell your agents to read .context/ before acting

The CLI automates the scaffolding, provides smart defaults, and adds quality-of-life tooling around the protocol.

Quick Start

# Scaffold a new workspace
npx @pedrocivita/tocket init

# Or just the essentials (3 files)
npx @pedrocivita/tocket init --minimal

# Configure your agents (optional — defaults to Claude Code + Gemini)
npx @pedrocivita/tocket config --architect "Gemini" --executor "Claude Code"

# Or open the interactive dashboard
npx @pedrocivita/tocket

That's it. Your repo now has a Memory Bank. Every AI session starts by reading .context/activeContext.md.

Safe testing — use a branch

Tocket writes files to your repo, but you can try it risk-free on a branch:

git checkout -b test/tocket-setup
npx @pedrocivita/tocket init
git add .context/ TOCKET.md CLAUDE.md GEMINI.md
git commit -m "chore: scaffold Tocket workspace"

# Try it out — run some AI sessions, see if you like it
# Don't like it? Clean up:
npx @pedrocivita/tocket eject     # removes all Tocket files
# Or just delete the branch:
git checkout main && git branch -D test/tocket-setup

See the Developer Guide for detailed safe-testing workflows.

Commands

CI-friendly flags

Every interactive command has flags for non-interactive use:

# Minimal init (3 files instead of 9)
tocket init --minimal --name myproject --description "My app" --force

# Sync without prompt
tocket sync --summary "Fixed auth bug and added tests"

# Generate to stdout or file instead of clipboard
tocket generate --to stdout
tocket generate --to payload.xml

# Verify executor followed the payload
tocket diff
tocket diff --json

# Handoff context to a new session
tocket handoff --to stdout

How it works

Memory Bank

The .context/ directory is the project's shared memory. Agents read it before acting and update it after completing work. Context lives in files, not in chat history.

Triangulation

For complex tasks, Tocket separates planning from implementation:

Architect (any planning AI)         Executor (any coding AI)
     |                                   |
     |  1. Reads .context/               |
     |  2. Analyzes task                 |
     |  3. Generates <payload> XML       |
     |-------- structured handoff ------>|
     |                                   |  4. Reads .context/ + payload
     |                                   |  5. Implements tasks
     |                                   |  6. Updates .context/
     |<-------- tocket diff report ------|

The Architect doesn't write code. The Executor doesn't make architecture decisions. The payload XML is the contract between them. After execution, tocket diff verifies compliance — did the Executor touch the right files? Are done criteria met? For simple tasks, a single agent can fill both roles.

Closing the loop

# After the Executor finishes work:
tocket diff                    # compare payload targets vs actual git changes
tocket diff --json             # machine-readable output
tocket diff --since HEAD~3     # diff against a specific ref

# Starting a new session (next day, new chat):
tocket handoff                 # copies context summary to clipboard
tocket handoff --to stdout     # print instead
tocket handoff --commits 10    # include more history
tocket handoff --since 1d      # files modified in last day

Who is this for?

• Developers using multi-agent setups (Gemini + Claude, Cursor + Copilot, etc.)
• Teams that want reproducible AI-assisted development across sessions
• Anyone tired of re-explaining project context to AI every time they open a chat
• Open-source maintainers who want contributors' AI agents to follow project conventions

How is Tocket different?

Configuration

Configure your preferred agents and defaults:

# Configure your agent roles
tocket config --architect "Gemini" --executor "Claude Code"

# Set payload defaults
tocket config --author "Your Name" --priority medium --skills "core,lsp"

# Or use the interactive setup (sections: Identity, Agent Roles, Payload Defaults)
tocket config

# View current config
tocket config --show

Config is stored at ~/.tocketrc.json.

Supported Agents

Tocket auto-generates the correct instruction file for each agent:

Don't see your agent? It still works — unknown agents get generic files, and you can override any template via ~/.tocket/templates/.

Documentation

Contributing

We welcome contributions! Visit tocket.ai for an overview of the framework, then read our Contributing Guide to get started.

This project follows a Code of Conduct.

License

MIT