Tessera

Small pieces. Masterpiece software.

Tessera is a state management harness for autonomous AI development. It has no LLM dependency and relies entirely on agents to drive the development process through composable skills.

What is Tessera?

Tessera manages what needs to be done (state). Agents figure out how to do it (intelligence).

You: "Build user authentication"
  ↓
Agent (with analyzer skill): Breaks into tasks
  ↓
Tessera: Stores tasks in database
  ↓
Agent (with Workflow skill): Claims task → writes test → implements → commits
  ↓
Tessera: Updates state, tracks progress
  ↓
You: Review and deploy

Key Features

• Pure State Management: No LLM bundled, zero API keys in CLI
• Agent-Driven: All intelligence handled by agents via skills
• Zero Native Dependencies: Uses sql.js (pure JavaScript SQLite), no external database installation
• Optimistic Concurrency: Safe parallel agent operations
• Context Sharing: What one agent learns, all agents can use
• Skill-Based: Composable skills teach agents capabilities
• Agent Agnostic: Works with Claude, GPT, local models, any AI

Quick Start

One-Line Installation

For Claude Code (Recommended):

curl -fsSL https://raw.githubusercontent.com/gatolim/tessera/master/scripts/setup-claude-code.sh | bash

For Cursor:

curl -fsSL https://raw.githubusercontent.com/gatolim/tessera/master/scripts/setup-cursor.sh | bash

The setup scripts will:

1. Install the Tessera CLI globally
2. Install everything-claude-code agents (specialized AI agents for autonomous development)
3. Install Tessera skills for your AI coding environment
4. Configure MCP server settings

Manual Installation

Install CLI, MCP Server, and Skills Installer:

npm install -g @gatolim/tessera-cli

This installs three commands:

• tessera - CLI for state management
• tessera-mcp - MCP server for AI integration
• tessera-skills - Skills installer for Claude Code/Cursor

Install everything-claude-code Agents (Optional):

npm install -g ecc-universal

Step 2: Configure MCP Server (Optional)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "tessera": {
      "command": "node",
      "args": ["/path/to/@gatolim/tessera-cli/dist/mcp/server.js"]
    }
  }
}

Step 3: Install Skills (Optional)

Run the skills installer to add Tessera skills to your AI coding environment:

tessera-skills

First Project

# Create a new project
mkdir my-project
cd my-project

# Initialize Tessera
tessera init

# Your agent handles the rest
# Agent uses analyzer skill to create tasks
# Agent uses workflow skill to implement features
# Tessera tracks all state and progress

# Check progress
tessera status

See Deployment Guide for detailed installation instructions.

Documentation

Getting Started

• Deployment Guide - Installation for all environments
• Quick Start Scripts - One-line installation scripts

Configuration

• Workspace Isolation - Git worktree support, TESSERA_WORKSPACE
• MCP Server - Model Context Protocol integration

Core Documentation

• Architecture - Agent-driven design philosophy
• Skills - Agent skills documentation
  • @tessera/primitives - Core CLI operations
  • @tessera/tdd-workflow - TDD development cycle
  • @tessera/analyze-requirements - Requirements analysis & task generation
• CLI Reference - Command reference

Contributing

• Contributing - Contribution guidelines

Why Agent-Driven?

Clean Separation

• Tessera: Manages state only (what needs to be done)
• Agents: Handle all intelligence (how to do it)
• Skills: Teach agents specific capabilities

Maximum Flexibility

• Agents use their preferred LLM (Claude, GPT, Ollama, etc.)
• Developers customize analyzer and workflow strategies
• No API keys in Tessera core
• Local/private LLM support

True Autonomy

• Agents self-organize and coordinate
• Skills are composable and extensible
• Multiple agents collaborate safely
• Humans provide oversight only

CLI Commands

For Humans

# Initialize Tessera in project
tessera init

# Show project status
tessera status

# Show help
tessera help

Git Worktree Support

For git worktree setups, share task database across worktrees:

# Set shared workspace location
export TESSERA_WORKSPACE=/path/to/main/repo

# All worktrees now share the same task database
cd ../worktree-feature-a
tessera task claim  # Uses shared database

cd ../worktree-feature-b
tessera task claim  # Uses same shared database

See Workspace Isolation for details.

For Agents (via Skills)

# Create task from analyzer
tessera task create --json '{"id":"task-id","title":"..."}'

# Claim next available task
tessera task claim --workflow implement --agent-id claude-1

# Update task progress
tessera task update <id> --step write_tests --status in_progress

# Mark task complete
tessera task complete <id>

# Share learned information
tessera context set test_framework jest
tessera context get test_framework

# List tasks
tessera task list --status pending
tessera task show <id>

Skills System

Skills teach agents how to use Tessera and implement workflows:

Core Skills

| Skill | Purpose | |-------|---------| | @tessera/primitives | Core CLI operations (init, create, claim, update, complete) | | @tessera/tdd-workflow | TDD development cycle (RED → GREEN → coverage → commit) | | @tessera/analyze-requirements | Project initialization, requirements analysis, task generation from PRD and technical documents |

@tessera/tdd-workflow Dependencies

The TDD workflow skill uses the following skills from everything-claude-code:

Testing Skills:

• /tdd - JavaScript TDD workflow
• /go-test - Go testing with table-driven tests
• /python-test - Python testing with pytest

Review Skills:

• /code-review - Comprehensive code review
• /go-review - Go-specific code review
• /python-review - Python-specific code review

Security Skills:

• /security-review - Security vulnerability scanning

Build Skills:

• /go-build - Go build error resolution
• /build-error-resolver - General build error fixing

Optional Skills:

• /e2e-runner - End-to-end testing with Playwright
• /refactor-cleaner - Dead code cleanup

Custom Skills

Developers can create custom skills for:

• Domain-specific patterns
• Company-specific workflows
• Custom integrations
• Specialized testing approaches

Task Model

{
  "id": "user-auth-jwt-login",
  "title": "User Authentication JWT Login",
  "category": "auth",
  "priority": 1,
  "description": "Create login endpoint with JWT access tokens (15min) and refresh tokens (7day)",
  "dependencies": ["user-model-schema", "bcrypt-utility"],
  "subtasks": [
    "Create POST /api/auth/login endpoint",
    "Validate email and password",
    "Compare password using bcrypt.compare()",
    "Generate JWT access token with 15min expiry",
    "Generate refresh token with 7day expiry",
    "Set httpOnly cookies",
    "Return {success, user}"
  ],
  "status": "pending",
  "workflow": "implement",
  "currentStep": null,
  "passes": null
}

See MVP Analysis for details.

Contributing

We welcome contributions! See CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Acknowledgments

Inspired by:

• Anthropic's Effective Harnesses

Recommended Companion:

• everything-claude-code - Comprehensive agent skills for testing, code review, security scanning, and more

Contact

• GitHub: https://github.com/gatolim/tessera

Tessera - Small pieces. Masterpiece software.