Getting Started with TeamContext

TeamContext is a team visibility platform for AI-assisted development. It works with any MCP-compatible AI coding tool — Claude Code, OpenAI Codex CLI, Google Gemini CLI, Cursor, Windsurf, and more.

TeamContext captures context from your team's coding sessions through two mechanisms:

• Hooks — Lightweight event handlers that run on session start, prompt submit, turn complete, and session end. These capture what you're working on without disrupting your workflow.
• MCP Server — A Model Context Protocol server that exposes 35+ tools your AI assistant can use to query team activity, create plans, manage handoffs, detect conflicts, and more — all from within your coding session.

With TeamContext, every team member can see what others are building, what decisions were made, and where potential conflicts exist — all without disrupting anyone's workflow.

Before installing TeamContext, make sure you have:

• Node.js 18+ — Required to run the CLI. Check with node --version
• npm — Comes with Node.js. Used to install the CLI globally.
• Git — Required for git hook integration and repository detection. Check with git --version
• An AI coding tool — At least one of: Claude Code, OpenAI Codex CLI, or Google Gemini CLI installed on your machine.

Before using the CLI, you need a TeamContext account and an API key:

TeamContext installs as a lightweight CLI tool. Setup is a two-step process:

Step 1: Initialize the CLI

Install the CLI globally and connect it to your TeamContext account:

The init command will prompt you for:

• API URL — Press Enter to accept the default (https://api.teamcontext.ai)
• API Key — Paste the key you generated in the dashboard

The CLI validates your key, then saves your config to ~/.teamctx/config.json with your team ID, user ID, and team name.

Step 2: Set up your AI tools

Run setup inside your project directory to auto-detect and configure your AI coding tools:

The setup command auto-detects which AI tools you have installed and prompts you to choose which to configure. For each selected tool, it installs:

• Event hooks — Capture session starts, prompts, responses, and session ends
• MCP server config — A .mcp.json file so your AI can access TeamContext tools
• Instruction file — A markdown file (e.g. CLAUDE.md) telling your AI when and how to use TeamContext
• Git post-commit hook — Automatically captures every git commit

You can also target specific tools with flags:

When you run teamctx setup --claude-code (or select Claude Code during interactive setup), the CLI configures the following:

Event Hooks

Added to .claude/settings.json in your project:

• SessionStart — Creates a session and shows team activity summary (who's online, recent decisions, conflicts)
• UserPromptSubmit — Captures each prompt you send to Claude
• Stop — Captures the full turn: tools used, files touched, model, tokens, conversation log, and git changes
• SessionEnd — Ends the session and triggers AI summarization

MCP Server

A .mcp.json file is created in your project root, making 35+ TeamContext tools available to Claude:

Instruction File

A CLAUDE.md file is added to your project, instructing Claude to use TeamContext MCP tools for team questions, plans, decisions, and conflict detection instead of relying on local git alone.

When you run teamctx setup --codex-cli, the CLI configures:

Event Hooks

Two configuration files are updated in your home directory:

• ~/.codex/config.toml — A notify hook is added to capture every turn completion
• ~/.codex/hooks.json — SessionStart and Stop events are registered for session lifecycle tracking

What Gets Captured

• Session start and end with thread ID tracking
• Every turn: prompt, response, branch, and metadata
• Sessions auto-close after 30 minutes of inactivity

Additional Files

• .mcp.json — MCP server config (same as Claude Code)
• AGENTS.md — Instruction file for Codex, telling it to use TeamContext tools

When you run teamctx setup --gemini-cli, the CLI configures:

Event Hooks

Added to .gemini/settings.json in your project:

• SessionStart — Creates a session and outputs team context as JSON
• BeforeAgent — Captures each prompt before Gemini processes it
• AfterAgent — Captures the response, tools used, files touched, and model info
• SessionEnd — Ends the session and triggers summarization

Additional Files

• .mcp.json — MCP server config (same format as other tools)
• .gemini/GEMINI.md — Instruction file for Gemini, guiding it to use TeamContext MCP tools

TeamContext installs a post-commit git hook automatically during setup. This works independently of any AI tool and captures every git commit your team makes.

What Gets Captured

• Commit message, author, branch, and file changes
• Diff stats (files added, modified, deleted)
• Repository identifier (owner/repo from git remote)
• Links to active AI session if one is running

How It Works

The hook runs asynchronously after every git commit — it never blocks your workflow. Data is sent to the TeamContext API in the background. Sensitive files (.env, .key, .pem) are automatically filtered out.

To install the git hook separately (without AI tool hooks):

For monorepos or workspaces with multiple git repositories, the CLI automatically detects child repos up to 2 levels deep and installs hooks in each one.

After setup, run the doctor command to verify everything is configured correctly:

The doctor command performs the following checks:

If any check fails, the doctor command provides specific remedial instructions to fix the issue.