Quickstart¶

Get Context Teleport running in your project in under 5 minutes. By the end of this page, your agent will have a shared context store it can read and write through natural language.

1. Initialize the store¶

Navigate to your project root and create a context store:

cd ~/my-project
uvx context-teleport init --name my-project

cd ~/my-project
context-teleport init --name my-project

This creates a .context-teleport/ directory inside your project with a manifest.json, empty knowledge/, decisions/, conventions/, and skills/ directories, and a state/ directory for session tracking.

my-project/
  .context-teleport/
    manifest.json
    knowledge/
    decisions/
    conventions/
    skills/
    state/
    sessions/

2. Register with your agent tool¶

Register the MCP server so your agent can discover and use it:

context-teleport register claude-code

context-teleport register cursor

context-teleport register gemini

context-teleport register opencode

context-teleport register

After registration, the agent tool spawns the MCP server automatically when it starts a session. You do not need to run anything manually.

3. Open your agent and start working¶

Launch your agent tool in the project directory. Context Teleport provides auto-onboarding: on session start, the agent receives a summary of the project's conventions, knowledge, decisions, skills, current task, and recent history.

Here is what a typical interaction looks like:

Save knowledge¶

You: "Save that we're using hexagonal architecture with FastAPI for the backend"
Agent: [calls context_add_knowledge with key="architecture" and content="..."] Done.

The agent writes a markdown file at .context-teleport/knowledge/architecture.md with the content you described.

Record a decision¶

You: "Record the decision to use PostgreSQL over MongoDB for the primary database"
Agent: [calls context_record_decision with title, context, decision, consequences]
      Decision ADR-0001 recorded.

Decisions follow an ADR (Architecture Decision Record) format with structured fields for context, the decision itself, and expected consequences.

Create a skill¶

You: "Create a skill for our deploy-staging workflow"
Agent: [calls context_add_skill with name="deploy-staging", description, instructions]
      Skill 'deploy-staging' saved.

Skills are reusable agent capabilities stored as SKILL.md files with YAML frontmatter and markdown instructions.

Set a team convention¶

You: "We always use feature branches and never force-push to main. Save that as a convention."
Agent: [calls context_add_convention with key="git", content="..."] Done.

Conventions are team behavioral rules that every agent should follow. They appear before knowledge in onboarding instructions.

Search context¶

You: "What do we know about authentication?"
Agent: [calls context_search with query="authentication"]
      Found 2 results: knowledge/auth-strategy.md (line 3, score 0.95),
      decisions/0002.md (line 12, score 0.72)

Sync with the team¶

You: "Sync context with the team"
Agent: [calls context_sync_push] Pushed 3 changes to remote.

You: "Pull latest context"
Agent: [calls context_sync_pull] Pulled 2 changes. No conflicts.

4. Check what you have¶

From the terminal, you can inspect the store at any time:

context-teleport status

This shows the project name, schema version, number of knowledge entries, decisions, skills, current task, and registered adapters.

You can also list entries directly:

# List all knowledge entries
context-teleport knowledge list

# Read a specific entry
context-teleport knowledge get architecture

# List all conventions
context-teleport convention list

# List all decisions
context-teleport decision list

# List all skills
context-teleport skill list

What happens under the hood¶

1. init creates the .context-teleport/ directory with a versioned manifest and empty content directories
2. register writes an MCP server entry to the tool's config file, pointing to context-teleport (via uvx or local path)
3. When the agent starts, it spawns context-teleport over stdio as an MCP server
4. The server auto-generates onboarding instructions from the store state
5. The agent reads context via MCP resources (context://conventions, context://knowledge, context://decisions, etc.)
6. The agent writes context via MCP tools (context_add_convention, context_add_knowledge, context_record_decision, etc.)
7. Sync operations commit to the local git repo and push/pull from the remote

Next steps¶

• First Project -- Extended tutorial covering the full lifecycle: remote setup, team onboarding, skills, sync, and conflict handling
• Adapter Workflows -- Import existing context from Claude Code, Cursor, Gemini, or other tools
• Skill Management -- Create, share, and improve reusable agent skills
• Team Setup -- Configure git remotes and team workflows