This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/docs/AGENTS.md
2026-06-22 17:45:56 +03:00

20 KiB

AI Tools — Architecture & Reference

This document is the single-source reference for every AI tool integrated into the gitgram-ai monorepo. All tools live under aitimemachine/ and are wired together through the AITM MCP server.


Table of Contents

  1. Architecture overview
  2. Starting each tool
  3. Analyzing codebases with GitNexus
  4. A2A protocol — how it works and how to register agents
  5. MCP tools reference
  6. Quick-start guide

1. Architecture Overview

gitgram-ai/
├── aitimemachine/
│   ├── mcp/                 # AITM MCP server — central hub, exposes all tools
│   ├── api-server/          # REST API for TimeMachine state (Drizzle/Neon)
│   ├── gitnexus/            # Graph-powered code intelligence, 17 MCP tools
│   ├── a2a/                 # A2A protocol types & JSON-RPC helpers
│   ├── context7/packages/mcp/  # Context7 MCP — up-to-date library docs
│   ├── beads/               # Go CLI for distributed graph issue tracking (bd)
│   ├── pal-mcp-server/      # PAL MCP — multi-model AI orchestration
│   └── tools/
│       ├── repo2txt/        # React/Vite UI: convert repos to LLM-readable text
│       └── repo-to-text/    # Python CLI: same conversion, CLI variant
└── scripts/
    ├── setup-aitm-tools.sh  # One-shot build of all companion tools
    └── start-all-dev.sh     # Start core dev services with concurrently

How the pieces connect

Claude Code / Cursor / any MCP client
          │
          ▼
  ┌───────────────────────────────────────┐
  │         AITM MCP server               │
  │  aitimemachine/mcp  (port: stdio)     │
  │                                       │
  │  Tool groups:                         │
  │  • tm_*          — TimeMachine core   │
  │  • gn_* proxy    — GitNexus tools     │
  │  • tm_docs_*     — Context7 tools     │
  │  • a2a_*         — A2A agent tools    │
  │  • before/after_action                │
  └──────────┬──────────────┬────────────┘
             │              │
             ▼              ▼
  ┌──────────────┐  ┌──────────────────┐
  │   GitNexus   │  │    Context7 MCP  │
  │  :3001/msg   │  │    :3100/msg     │
  └──────────────┘  └──────────────────┘

The AITM MCP server is the single entry point for AI clients. It embeds the TimeMachine engine directly and proxies GitNexus and Context7 over HTTP/JSON-RPC. PAL MCP and Beads run as independent services alongside it.

Tool inventory

Tool Location Language Purpose
AITM MCP server aitimemachine/mcp TypeScript Central MCP hub; checkpoint, restore, session, file, worktree, S3, Docker capsule tools
GitNexus aitimemachine/gitnexus TypeScript Code knowledge graph: query, impact, trace, rename, route/tool maps
PAL MCP Server aitimemachine/pal-mcp-server Python Multi-model AI orchestration (chat, code review, debug, plan, consensus)
Context7 aitimemachine/context7/packages/mcp TypeScript Up-to-date library documentation injected into LLM context
Beads (bd) aitimemachine/beads Go Distributed graph issue tracker for AI agents (Dolt-powered)
A2A protocol aitimemachine/a2a TypeScript JSON-RPC 2.0 agent-to-agent protocol types and SDK
repo2txt aitimemachine/tools/repo2txt TypeScript/React UI to convert a GitHub repo or local directory to LLM-readable text
repo-to-text aitimemachine/tools/repo-to-text Python CLI to convert a directory to structured XML/text for LLM prompts

2. Starting Each Tool

All commands below are root-level npm scripts. Run them from the monorepo root (/Users/arhansubasi/gitgram-ai/ or wherever you cloned the repo).

AITM MCP server

npm run dev:aitm-mcp
# Starts aitimemachine/mcp in watch mode (stdio transport)

Configure your MCP client to launch it via the mcp.json at aitimemachine/mcp/mcp.json. The aitm server entry uses node dist/index.js.

Environment variables recognised by the server:

Variable Default Purpose
GITNEXUS_URL http://localhost:3001 Where to proxy GitNexus tool calls
CONTEXT7_URL http://localhost:3100 Where to proxy Context7 tool calls
AITM_A2A_AGENTS [] JSON array of { name, url } to register A2A agents
AITM_EXPERIMENTAL_TOOLS 0 Set to 1 to enable experimental tools
DISABLED_TOOLS — Comma-separated list of tool names to disable

AITM API server

npm run dev:aitm-api        # standard dev mode
npm run dev:aitm-api:clean  # dev mode with a clean database

Serves the TimeMachine REST API at http://localhost:3001 by default.

GitNexus

npm run dev:gitnexus        # starts the GitNexus HTTP server at :3001
npm run dev:gitnexus-web    # starts the GitNexus web UI

GitNexus must have at least one repo indexed before it can answer queries. See Section 3 for indexing instructions.

PAL MCP Server

npm run dev:pal-mcp
# Runs aitimemachine/pal-mcp-server/run-server.sh (activates Python venv, starts server)

Configure providers by creating a .env in aitimemachine/pal-mcp-server/ based on the requirements.txt instructions. At minimum set one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY.

Context7

npm run dev:context7
# Starts aitimemachine/context7/packages/mcp/dist/index.js
# (falls back to node directly if the package has no dev script)

Listens on port 3100 by default. No API key required for public libraries; set CONTEXT7_API_KEY for higher rate limits and private repositories.

Beads (bd)

npm run build:beads
# Compiles Go binary to aitimemachine/beads/bd

After building, use the binary directly:

aitimemachine/beads/bd init          # initialise in any project
aitimemachine/beads/bd setup claude  # install Claude Code hooks
aitimemachine/beads/bd ready         # list unblocked tasks
aitimemachine/beads/bd prime         # print agent workflow context

repo2txt (React/Vite UI)

npm run dev:repo2txt
# Vite dev server for the repo2txt web UI

repo-to-text (Python CLI)

npm run dev:repo-to-text
# python -m repo_to_text from aitimemachine/tools/repo-to-text

Install the Python package once before first use:

pip install repo-to-text

Start all core services at once

bash scripts/start-all-dev.sh
# Requires: npm install -g concurrently
# Starts: gitgram/backend (:3000), gitgram/web (:3002), aitimemachine/api-server (:3001)

Port overrides:

GITGRAM_BACKEND_PORT=3000 GITGRAM_WEB_PORT=3002 AITM_API_PORT=3001 \
  bash scripts/start-all-dev.sh

3. Analyzing Codebases with GitNexus

GitNexus builds a queryable knowledge graph (nodes = symbols, edges = calls/imports/ inheritance) from a TypeScript or JavaScript codebase. You must index a repo before the graph tools return useful results.

Using the convenience script

# From monorepo root
bash scripts/analyze-with-gitnexus.sh <REPO>

Supported <REPO> aliases:

Alias Path
gitgram-backend gitgram/backend
gitgram-web gitgram/web
aitm-api aitimemachine/api-server
aitm-mcp aitimemachine/mcp

The script auto-builds the GitNexus CLI if dist/cli/index.js is missing, then calls gitnexus analyze <path> --name <name>.

Using the CLI directly

cd aitimemachine/gitnexus

# Index a repo (run from its root, or pass --root)
node dist/cli/index.js analyze /absolute/path/to/repo --name my-repo

# Start the query server
npm run serve          # or: node dist/cli/index.js server
# Default: http://localhost:3001

# Query via CLI
node dist/cli/index.js query "authentication flow"
node dist/cli/index.js context validateUser
node dist/cli/index.js impact AuthService

Using GitNexus through the AITM MCP server

Once the GitNexus server is running and GITNEXUS_URL points at it, all gn_* tools become available inside the AITM MCP server automatically. Example in Claude Code:

list all indexed repos → calls gn_list_repos
query "how does checkout work" → calls gn_query
impact analysis for PaymentService → calls gn_impact

Using GitNexus with MCP directly (without AITM)

# Claude Code
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# or add to .mcp.json
{
  "mcpServers": {
    "gitnexus": {
      "command": "node",
      "args": ["aitimemachine/gitnexus/dist/cli/index.js", "mcp"]
    }
  }
}

4. A2A Protocol

The A2A (Agent-to-Agent) protocol is a Google-authored open standard for agents to delegate tasks to other agents over HTTP using JSON-RPC 2.0. The implementation in aitimemachine/a2a provides TypeScript types and the a2a_* MCP tools.

How it works

  1. Every A2A agent exposes a POST /a2a endpoint that accepts JSON-RPC 2.0 requests.
  2. The caller sends a tasks/send request with a message (array of Part objects).
  3. The agent executes the task and returns a Task object with a status field (submitted, working, completed, failed, or canceled).
  4. The caller can poll with tasks/get using the same id until the task completes.
Caller                               Agent
  │                                    │
  │  POST /a2a                         │
  │  { method: "tasks/send",           │
  │    params: { id, message } }  ──► │
  │                                    │  (executes)
  │  ◄─── { result: Task }            │
  │                                    │
  │  POST /a2a                         │
  │  { method: "tasks/get",            │
  │    params: { id } }           ──► │
  │  ◄─── { result: Task{status} }    │

Registering agents

Set the AITM_A2A_AGENTS environment variable before starting the AITM MCP server. It must be a JSON array of { name, url } objects:

export AITM_A2A_AGENTS='[
  { "name": "code-reviewer", "url": "http://localhost:4001" },
  { "name": "planner",       "url": "http://localhost:4002" }
]'
npm run dev:aitm-mcp

Or set it in aitimemachine/mcp/mcp.json:

{
  "mcpServers": {
    "aitm": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "AITM_A2A_AGENTS": "[{\"name\":\"code-reviewer\",\"url\":\"http://localhost:4001\"}]"
      }
    }
  }
}

Using A2A tools inside Claude Code

# List registered agents
a2a_list_agents

# Dispatch a task to an agent
a2a_send_task
  agentUrl: "http://localhost:4001"
  taskId: "review-pr-42"
  message: "Review the auth module for security issues"

# Poll for completion
a2a_get_task
  agentUrl: "http://localhost:4001"
  taskId: "review-pr-42"

Building an A2A-compatible agent

Any HTTP server that implements POST /a2a accepting JSON-RPC 2.0 qualifies. Import the shared types from the monorepo package:

import type { Task, TaskStatus, Part, TextPart } from 'aitimemachine/a2a';

The aitimemachine/a2a package also exports AGENT_CARD_PATH (/.well-known/agent.json) and the AgentCard schema for agent discovery.


5. MCP Tools Reference

The AITM MCP server registers tools in eight groups. All tools are available to any MCP-compatible client pointing at aitimemachine/mcp.

5.1 TimeMachine core tools

Tool Description
tm_project_init Initialize or register a project for time tracking
tm_set_project Set the current working project
tm_checkpoint_create Create a checkpoint (snapshot of current state)
tm_checkpoint_list List all checkpoints/timepoints
tm_checkpoint_restore Restore project to a checkpoint
tm_checkpoint_preview Preview what restore would change
tm_diff Show diff between two checkpoints or checkpoint and current state
tm_diff_checkpoints Detailed diff between two checkpoints (files + chat + terminal)
tm_event_append Append an event to the project timeline
tm_timeline Get timeline of events for a project
tm_search Search across conversations and checkpoints
tm_find_restore Search conversations and find the best checkpoint to restore
tm_log_message Log a conversation message
tm_stats Get TimeMachine statistics
tm_tag Tag a checkpoint with a label
tm_ready Check if the TimeMachine daemon is ready
before_action Call before making file changes — creates an automatic checkpoint
after_action Call after making file changes — records what was done

5.2 Session tools

Tool Description
tm_session_capture Capture current state as a session (used by the daemon)
tm_session_list List all captured sessions
tm_bisect Binary search to find when a test started failing

5.3 Integration/environment tools

Tool Description
tm_container_state Get Docker/container state for a project
tm_database_state Get database state for a project
tm_gemini_sessions List Gemini CLI sessions
tm_git_state Get git state for a project
tm_env_state Get environment state (runtimes, package managers, dependencies)
tm_aider_sessions List Aider sessions
tm_cursor_workspaces List Cursor workspaces
tm_claude_projects List Claude Code projects
tm_claude_conversations Get Claude Code conversations for a project

5.4 Storage / S3 / Docker capsule tools

Tool Description
tm_s3_config Configure S3 backup credentials
tm_s3_backup Backup all TimeMachine data to S3
tm_s3_restore Restore all TimeMachine data from S3
tm_capsule_create Create a Docker capsule for deterministic execution
tm_capsule_exec Execute a command inside a capsule container
tm_capsule_stop Stop and remove a capsule container

5.5 File tools

Tool Description
tm_restore_files Restore specific files from a session (glob patterns supported)
tm_get_file_at Get file content at a specific checkpoint
tm_file_history Get history of a file across checkpoints
tm_prompt_debug_regression Generate a prompt to debug regressions between two checkpoints
tm_prompt_write_postmortem Generate a prompt to write an incident postmortem
tm_prompt_generate_repro_steps Generate reproduction steps from checkpoint history
tm_repo_to_text Convert a repository or directory to a single text block for LLM context

5.6 Worktree tools

Tool Description
tm_worktree_list List active AITM worktrees for the current project
tm_worktree_restore Restore a worktree to a checkpoint
tm_worktree_cleanup Remove all AITM worktrees for the current project

5.7 GitNexus proxy tools (prefix: none, routed to GitNexus server)

These tools forward calls to the GitNexus server at GITNEXUS_URL.

Tool Description
list_repos List indexed repositories (paginated)
query Query the code knowledge graph for execution flows related to a concept
cypher Execute a Cypher query directly against the knowledge graph
context 360-degree view of a single symbol: incoming/outgoing references, callers, callees
detect_changes Analyze uncommitted git changes and find affected execution flows
check Run read-only structural checks (circular imports, etc.)
rename Multi-file coordinated rename using the knowledge graph
impact Analyze the blast radius of changing a code symbol
explain Explain persisted taint findings from gitnexus analyze --pdg
pdg_query Query the Program Dependence Graph (control + data flow)
route_map Show API route mappings: which components fetch which endpoints
tool_map Show MCP/RPC tool definitions and their handlers
shape_check Check API response shapes against their consumers
api_impact Pre-change impact report for an API route handler
group_list List configured repository groups
group_sync Rebuild the Contract Registry for a group
trace Find the shortest directed path between two symbols

5.8 Context7 documentation tools

Tool Description
tm_docs_resolve Resolve a library name (e.g. "react") to its Context7 library ID
tm_docs_query Query documentation for a resolved Context7 library ID
tm_docs_for_imports Detect imports in a source file and fetch docs for each library

5.9 A2A tools

Tool Description
a2a_send_task Send a task to an A2A agent via tasks/send
a2a_get_task Get the current status of an A2A task via tasks/get
a2a_list_agents List agents registered in AITM_A2A_AGENTS

6. Quick-Start Guide

Step 1 — Build companion tools

Run this once after cloning the repo or pulling major updates:

bash scripts/setup-aitm-tools.sh

This script builds four tools in sequence (a failure in one does not abort the others):

Tool What it does
beads go build ./cmd/bd/... → binary at aitimemachine/beads/bd
gitnexus npm install && npm run build in aitimemachine/gitnexus/gitnexus
pal-mcp-server Creates Python venv and installs requirements.txt
context7-mcp pnpm/npm install && build in aitimemachine/context7/packages/mcp

Prerequisites:

  • Node.js 18+ and npm
  • Python 3.10+ (for PAL MCP server)
  • Go 1.21+ (for Beads; skipped gracefully if missing)
  • pnpm (preferred for context7; falls back to npm)

Step 2 — Start core dev services

bash scripts/start-all-dev.sh

Services started:

Service Default port
gitgram/backend 3000
aitimemachine/api-server 3001
gitgram/web 3002

Requires concurrently globally installed (npm install -g concurrently). Without it the script prints manual commands for three separate terminals.

Step 3 — Start the AI tool layer

In a separate terminal (or add to your concurrently invocation):

# AITM MCP server (required — hub for all AI tools)
npm run dev:aitm-mcp

# GitNexus server (required for gn_* tools)
npm run dev:gitnexus

# Context7 (optional — for tm_docs_* tools)
npm run dev:context7

# PAL MCP (optional — for multi-model AI)
npm run dev:pal-mcp

Step 4 — Index your codebase with GitNexus

bash scripts/analyze-with-gitnexus.sh gitgram-backend
bash scripts/analyze-with-gitnexus.sh aitm-mcp

Step 5 — Point your MCP client at the AITM server

Add the following to your MCP client config (e.g. ~/.claude/mcp.json or Claude Code's claude mcp add command):

{
  "mcpServers": {
    "aitm": {
      "command": "node",
      "args": ["/absolute/path/to/aitimemachine/mcp/dist/index.js"],
      "env": {
        "GITNEXUS_URL": "http://localhost:3001",
        "AITM_A2A_AGENTS": "[]"
      }
    }
  }
}

Or use the pre-built mcp.json at aitimemachine/mcp/mcp.json, which also defines standalone entries for gitnexus, context7, and pal.

Step 6 — Verify everything is running

# Check the AITM API server
curl http://localhost:3001/health

# Check the GitNexus server
curl http://localhost:3001/health

# List indexed repos (from inside Claude Code)
# > list_repos