convez.ai
MCP ServerProdutividadeIntermediário
vishal-atlan

dev-context-capsule

vishal-atlan/dev-context-capsule

Recupere seu contexto de dev em segundos, nunca mais recarregue sua memória

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que captura e restaura o contexto de desenvolvimento mid-task, evitando perda de estado mental durante interrupções. Integra git, tickets (Linear/Jira), arquivos abertos e histórico Claude para gerar briefings automáticos quando você retorna a uma tarefa, com busca TF-IDF e hooks git de zero-fricção.

Instalação

$npx convez-ai vishal-atlan/dev-context-capsule

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Resumir estado de debug após interrupções ou troca de branch
  • Acompanhar progresso em múltiplos tickets e PRs simultaneamente
  • Pesquisar contexto anterior por palavra-chave em cápsulas salvas
  • Automatizar captura de estado via git hooks pré-push e pós-checkout

Veredito

Ferramenta bem arquitetada que resolve um problema real em fluxos de desenvolvimento fragmentados. A integração profunda com git, tickets e sessões Claude é sofisticada; recomendada para equipes que alternam contexto frequentemente e precisam recuperar estado mental rapidamente.

README

A tradução para o português deste README ainda está na fila.

dev-context-capsule

Never lose your mental state mid-task again.

You're deep in a debugging session — 2 hours in, you've narrowed the bug to one function, you know exactly what to check next. Then a meeting pulls you away, or you switch branches for a hotfix. You come back the next morning and spend 30 minutes re-loading your brain.

dev-context-capsule fixes that. It's an MCP server that captures your dev context mid-task (what you were trying, what you found, what the next step was) and briefs you when you return — like a colleague who was watching over your shoulder.


What it does

ActionWhat happens
captureReads your git state (branch, commits, staged/unstaged files), fetches the linked issue from the branch name (Linear or Jira), distills everything into a 3-5 sentence briefing via Claude, strips secrets, and saves to local SQLite
restoreLoads the latest capsule for your current branch, compares it against current git state, and generates a warm-up briefing: "You were trying to fix X, you'd narrowed it to Y, next step is Z"
ticket_statusFull context for any issue ticket: status + description, all PRs across repos (open/merged), and saved capsules — answers "where was I on PROJ-123?"
active_ticketsLists all your assigned in-progress tickets (Linear or Jira) with their PR status across repos
searchTF-IDF keyword search across all your saved capsules — find past context by topic
listSee all capsules for a repo, flagged if stale (>2 weeks old)
Git hooksAuto-fires capture/restore on branch switch or git push — zero friction

Architecture

flowchart TD
    DEV([Developer]) -->|branch switch / push| HOOKS[Git Hooks\npost-checkout · pre-push]
    DEV -->|natural language query| MCP

    HOOKS -->|capsule capture/restore| MCP[MCP Server\ncapsule/server.py]

    MCP --> CAP[Capture Agent\nagents/capture.py]
    MCP --> RES[Restore Agent\nagents/restore.py]
    MCP --> TKT[Ticket Context\nagents/ticket_context.py]
    MCP --> RAG[RAG Retriever\nrag/retriever.py]

    CAP --> GIT[Git Reader\nmcp_tools/git_reader.py]
    CAP --> LIN[Ticket Reader\nmcp_tools/ticket_reader.py]
    CAP --> VSCODE[VS Code Reader\nmcp_tools/vscode_reader.py]
    CAP --> CLS[Claude Session Reader\nmcp_tools/claude_session_reader.py]
    CAP --> SAN[Sanitizer\nguardrails/sanitizer.py]
    CAP --> LLM[LLM Layer\nagents/_llm.py]
    CAP --> DB[(SQLite\n~/.capsule/capsules.db)]

    RES --> DB
    RES --> GIT
    RES --> LLM

    TKT --> LIN
    TKT --> GH[GitHub Reader\nmcp_tools/github_reader.py]
    TKT --> DB

    RAG --> DB

    LLM --> OUT[Summary / Briefing]
    OUT --> DEV

Data flow — Capture

1. Git hook fires (or you call `capture` manually)
2. GitReader snapshots: branch, last 5 commits, staged/unstaged files + diff content (2000 chars)
3. VSCodeReader reads currently open files from ~/.capsule/vscode-open-files.json
4. TicketReader fetches linked ticket from branch name (Linear or Jira) — including last 5 comments
5. ClaudeSessionReader reads recent prompts from ~/.claude/projects/ — covers VS Code, terminal, Desktop
6. Store fetches last 3 capsule summaries for this branch (session memory)
7. Sanitizer strips secrets from the combined snapshot
8. LLM sees all 6 signals → distills a 3-5 sentence capsule that continues the narrative
9. Sanitizer strips secrets from LLM output (second pass)
10. Saved to SQLite keyed by abs(repo_path) + branch

Data flow — Restore

1. You switch to a branch / call `restore` manually
2. SQLite lookup: latest capsule for this branch
3. GitReader snapshots current state
4. LLM compares capsule vs current state → warm-up briefing
5. Briefing returned: what you were doing, what changed, first action to take

File structure

dev-context-capsule/
├── capsule/
│   ├── server.py               # MCP server — defines all 9 tools
│   ├── agents/
│   │   ├── _llm.py             # LLM client factory: anthropic / bedrock / litellm — zero hardcoding
│   │   ├── capture.py          # Reads git + ticket + open files → LLM → stores capsule
│   │   ├── restore.py          # Loads capsule → LLM → warm-up briefing
│   │   └── ticket_context.py   # Aggregates ticket + PRs + capsules for a ticket ID
│   ├── mcp_tools/
│   │   ├── git_reader.py       # GitPython: branch, commits, staged/unstaged files
│   │   ├── ticket_reader.py    # Router: shared TicketInfo type + provider dispatch
│   │   ├── linear_reader.py    # Linear GraphQL provider (TICKET_PROVIDER=linear)
│   │   ├── jira_reader.py      # Jira REST API provider (TICKET_PROVIDER=jira)
│   │   ├── github_reader.py        # gh CLI: PRs across repos matching a ticket ID
│   │   ├── vscode_reader.py        # Reads ~/.capsule/vscode-open-files.json from VS Code extension
│   │   └── claude_session_reader.py# Reads ~/.claude/projects/ — recent AI conversation prompts
│   ├── memory/
│   │   └── store.py            # SQLite CRUD at ~/.capsule/capsules.db
│   ├── rag/
│   │   └── retriever.py        # TF-IDF search across all capsules
│   ├── guardrails/
│   │   └── sanitizer.py        # Secret stripping + stale detection
│   └── hooks/
│       └── install.py          # Safe hook installer — chains existing hooks, zero tracked changes
├── vscode-extension/           # Companion VS Code extension (no compilation needed)
│   ├── extension.js            # Writes open tabs to ~/.capsule/vscode-open-files.json
│   └── package.json
├── docs/
│   └── architecture.md         # Deep-dive component breakdown
├── tests/
│   ├── test_sanitizer.py
│   └── test_linear_reader.py
├── pyproject.toml
├── SPEC.md                     # Original design spec — goals, architecture, phased build plan
├── CLAUDE.md                   # Claude Code project instructions
└── README.md

Installation

Prerequisites

  • Python 3.11+
  • uv (recommended) or pip
  • An LLM API key (Anthropic, AWS Bedrock, or any OpenAI-compatible proxy)

1. Clone and install

git clone https://github.com/vishal-atlan/dev-context-capsule.git
cd dev-context-capsule

# with uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# or with pip
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# if using AWS Bedrock or an OpenAI-compatible proxy, install the extra:
uv pip install -e ".[bedrock]"   # Bedrock only
uv pip install -e ".[litellm]"   # any OpenAI-compatible proxy (LiteLLM, etc.)

2. Configure your LLM provider

Pick one of the three providers below and add the env vars to your shell profile (~/.zshrc / ~/.bashrc).

Option A — Direct Anthropic API

export ANTHROPIC_API_KEY="sk-ant-..."

Option B — AWS Bedrock

export CAPSULE_LLM_PROVIDER=bedrock
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-east-1"   # or eu-north-1, ap-southeast-2, etc.
# Model is auto-selected from your region. Override with:
# export CAPSULE_MODEL="us.anthropic.claude-sonnet-4-6"

Option C — Any OpenAI-compatible proxy (LiteLLM, etc.)

export CAPSULE_LLM_PROVIDER=litellm
export CAPSULE_LITELLM_BASE_URL="https://your-proxy.example.com"
export CAPSULE_LITELLM_API_KEY="sk-..."
# export CAPSULE_MODEL="claude-sonnet-4-6"   # optional, defaults to claude-sonnet-4-6

Passthrough mode: If no provider is configured, capture and restore still work — they return structured markdown for Claude Code to interpret instead of calling an LLM directly. All other tools work regardless.

3. Verify

pytest tests/          # run tests
capsule --help         # confirm CLI is on PATH

Configuration

LLM provider env vars

VariableDescriptionDefault
CAPSULE_LLM_PROVIDERanthropic | bedrock | litellmAuto-detected from ANTHROPIC_API_KEY
CAPSULE_MODELModel name/ID (any provider)claude-sonnet-4-6 (bedrock: derived from region)
ANTHROPIC_API_KEYDirect Anthropic API key—
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGIONBedrock credentials—
CAPSULE_LITELLM_BASE_URLBase URL of your OpenAI-compatible proxy—
CAPSULE_LITELLM_API_KEYAPI key for the proxy—

Optional — Ticket integration

Set TICKET_PROVIDER to enable ticket_status, active_tickets, and automatic ticket enrichment at capture time.

Linear:

VariableHow
TICKET_PROVIDERexport TICKET_PROVIDER=linear (this is the default, so optional)
LINEAR_API_KEYexport LINEAR_API_KEY="lin_api_..." — from linear.app → Settings → API → Personal API keys

Jira:

VariableHow
TICKET_PROVIDERexport TICKET_PROVIDER=jira
JIRA_BASE_URLexport JIRA_BASE_URL="https://yourcompany.atlassian.net"
JIRA_EMAILexport JIRA_EMAIL="you@yourcompany.com"
JIRA_API_TOKENexport JIRA_API_TOKEN="..." — from id.atlassian.com/manage-profile/security/api-tokens

Optional — GitHub PR search

Set GITHUB_REPOS to configure which repos are searched by ticket_status:

export GITHUB_REPOS="org/repo-a,org/repo-b,org/repo-c"

Requires the gh CLI to be installed and authenticated (gh auth login).

Wire into Claude Code (MCP)

This is what lets you call capture and restore directly from a Claude Code conversation.

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dev-context-capsule": {
      "command": "capsule",
      "args": [],
      "env": {
        "CAPSULE_LLM_PROVIDER": "litellm",
        "CAPSULE_LITELLM_BASE_URL": "https://your-proxy.example.com",
        "CAPSULE_LITELLM_API_KEY": "sk-..."
      }
    }
  }
}

Or for direct Anthropic:

{
  "mcpServers": {
    "dev-context-capsule": {
      "command": "capsule",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

If capsule isn't on your PATH, use the full path: "/path/to/.venv/bin/capsule"

After adding, restart Claude Code. You'll see the tools available in any conversation.

Install git hooks into a repo

To enable auto-capture on branch switch and push for a specific repo:

python -m capsule.hooks.install /path/to/your/repo

This installs two hooks into the target repo's .git/hooks/:

  • post-checkout — auto-restores context when you switch branches
  • pre-push — auto-captures context before every push

Optional — VS Code open-files integration

Install the companion extension so capture also records which files you have open in VS Code — the highest-signal data point for context restoration.

1. Copy the extension into your VS Code extensions folder:

cp -r vscode-extension ~/.vscode/extensions/capsule-open-files-0.0.1

No marketplace install, no compilation — pure JavaScript.

2. Restart VS Code.

The extension activates on startup and writes ~/.capsule/vscode-open-files.json on every tab change. The capsule reader picks it up automatically — it's a silent no-op if VS Code isn't open.

Optional — set a custom storage path

By default capsules are stored at ~/.capsule/capsules.db. To override:

export CAPSULE_DB_PATH="/your/preferred/path/capsules.db"

Usage

Via Claude Code (recommended)

Once wired in as an MCP server, just talk to Claude:

Capture and restore:

"Capture my context here"
→ Capsule [a1b2c3d4] saved for branch `fix/orders-n+1`.
  You were investigating an N+1 query in the orders API. You'd narrowed it
  to the eager-load on UserOrders line 84. The test in spec/orders_spec.rb
  was failing with a count mismatch. Next step was checking the includes()
  chain in the serializer.

"Restore my context"
→ CONTEXT RESTORED — branch `fix/orders-n+1`
  Welcome back. When you left, you were fixing an N+1 in the orders API,
  narrowed to line 84 of UserOrders. Since then, 2 new commits landed on
  main — none touch the orders path. Your next move: open spec/orders_spec.rb
  and run the failing test to confirm the eager-load hypothesis.

Ticket-centric queries (requires ticket provider credentials):

"Where was I on PROJ-123?"
→ # Context — PROJ-123

  ## Ticket
  **[PROJ-123](https://linear.app/...)** — Fix API rate-limit handling in sync job
    Status: In Progress | Assignee: You | Priority: High

  ## Pull Requests (1 total — 1 open, 0 merged, 0 closed)
  - 🟡 **[backend#47](...) — fix: retry with backoff on 429 responses
     Branch: `dev/proj-123-rate-limit` | OPEN | by you

  ## Where You Left Off (1 capsule)
  **backend** (branch: `dev/proj-123-rate-limit`)
  > Narrowed the 429s to the nightly sync job — it bursts 200 requests
  > in under a second on large datasets. Added exponential backoff in
  > sync_client.py. Next: add an integration test with a mock rate-limit server.
  _Captured: 2026-05-28 14:32_

"What are all my active tickets with PR status?"
→ # Active Tickets (3)

  ### [PROJ-123](...) — Fix API rate-limit handling in sync job
  Status: **In Progress** | Priority: High | PRs: 1 open PR

  ### [PROJ-145](...) — Add support for group filter by name
  Status: **In Progress** | Priority: Medium | PRs: no PRs | 2 capsules saved

  ### [PROJ-151](...) — Improve error messages on 403 responses
  Status: **Todo** | Priority: Medium | PRs: no PRs

Via CLI

# capture current context in a repo
capsule capture /path/to/repo

# restore context for current branch
capsule restore /path/to/repo

# list all saved capsules
capsule list_saved /path/to/repo

# search across capsules
capsule search "N+1 query" /path/to/repo

# delete a capsule by ID
capsule delete a1b2c3d4

What's not built yet

FeatureStatusNotes
Capsule encryption at restNot builtSQLite is plaintext; add SQLCipher for sensitive repos
Web UI / dashboardNot builtBrowse and search capsules visually
Team-shared capsulesNot builtPush capsules to a shared Postgres/Supabase store for handoffs
IDE close hookNot builtFire capture automatically when VS Code window closes (currently only fires on git push via hook)

Security

  • Secrets are stripped twice — before the LLM call and before storage
  • Patterns covered: JWTs, Bearer tokens, API keys, GitHub PATs, Slack tokens, AWS credentials, OpenAI/Anthropic keys
  • Capsules older than 14 days are flagged [STALE] on list/restore
  • The SQLite DB lives at ~/.capsule/capsules.db — local only, never synced

Contributing

PRs welcome. Run ruff check capsule/ before submitting.

Ver o original no GitHub

Bom para

Relacionados