██████╗████████╗██╗  ██╗
    ██╔════╝╚══██╔══╝╚██╗██╔╝
    ██║        ██║    ╚███╔╝ 
    ██║        ██║    ██╔██╗ 
    ╚██████╗   ██║   ██╔╝ ██╗
     ╚═════╝   ╚═╝   ╚═╝  ╚═╝

Context (ctx) - The Context Engine for AI Agents

Slash AI costs by 95%: From $1,125 to just $10/agent/month - the price of the upcoming ctx Pro subscription!

Beta Software: ctx is in beta. The API and schema may change. See CHANGELOG.md for release history.

Modern AI agents struggle with external tools because raw command output is token-expensive, unstructured, and lacks metadata. This wastes context windows and drives up costs.

ctx solves this by wrapping any command in a structured JSON "context envelope." It adds precise token counts, execution metadata, and telemetry, enabling agents to make smarter, cost-aware decisions.

The ctx Advantage: Drastic Cost Reduction

ctx enables a "measure-then-act" workflow that can reduce token consumption by over 95%.

Before ctx (Expensive): An agent gets a huge, raw text blob.

# Agent sends the entire raw output to the LLM
psql -c "SELECT * FROM users" | llm -p 'Summarize users'
# Result: ~25,000 tokens consumed (~$1,125/month)

With ctx (Efficient): The agent first checks the cost, then refines its query.

# 1. Measure the token cost first
ctx psql -c "SELECT * FROM users" | jq '.tokens'
# Result: 25000

# 2. Refine the query and execute safely
ctx psql -c "SELECT status, COUNT(*) FROM users GROUP BY status" | llm
# Result: ~100 tokens consumed (99.6% reduction)

This simple pattern transforms an expensive operation into a negligible one.

Supported Coding Agents

ctx integrates with leading AI coding assistants and agentic IDEs through simple setup commands. We're constantly expanding support to include more tools based on community needs.

AGENTS.md Support - ctx now supports the AGENTS.md standard, an open format for guiding coding agents that works across multiple AI tools. Run ctx setup agents to generate a universal AGENTS.md file that's compatible with Cursor, RooCode, OpenCode, and other agents that support this standard.

Want to see your favorite AI tool supported? Request a new integration by creating a GitHub issue.

Key Features

• Universal Tool Wrapper: Works with any CLI tool out-of-the-box (psql, git, docker, kubectl, ls, etc.).
• Structured JSON Output: Enriches raw output with vital metadata for LLMs.

  {
    "tokens": 42,
    "output": "...",
    "input": "...",
    "metadata": { "success": true, "exit_code": 0, "duration": 127 },
    "telemetry": { "trace_id": "...", "span_id": "..." },
    "schema_version": "0.1"
  }

• Precise Token Counting: Supports OpenAI, Anthropic, and Gemini tokenizers.
• Safety Controls: Set limits on tokens, output size, lines, and pipeline stages to prevent runaway costs.
• Streaming Support: Terminate long-running commands in real-time when limits are breached.
• Privacy-Aware: Instantly disable history and telemetry with a --private flag.

Installation & Updates

Recommended: Install Script (Full Features)

The recommended method is the one-liner script, which provides full versioning and auto-update capabilities:

curl -sSL https://raw.githubusercontent.com/slavakurilyak/ctx/main/scripts/install-remote.sh | bash

Features:

• Full version information
• Auto-update notifications
• ctx update command support
• Proper build metadata

Alternative Methods

Pre-built Releases (Full Features):
Download binaries from the Releases page.

• Full version information
• ctx update command support
• No auto-update notifications

Go Install (Limited Features):

go install github.com/slavakurilyak/ctx@latest

• Shows "ctx version unknown (built from source)"
• No auto-update capabilities
• Automatic Go module updates
• Tip: Run ctx update after installing to upgrade to a full-featured version

Updating ctx

Automatic Updates (Install Script & Pre-built):

ctx update                    # Update to latest stable version
ctx update --pre-release      # Include pre-releases
ctx update --check            # Check for updates without installing

Go Install Users:

go install github.com/slavakurilyak/ctx@latest  # Manual update
# Or upgrade to full version:
ctx update  # Replaces go install version with full-featured version

Verify installation: ctx version

Quick Start: Set Up Your AI Assistant

After installation, configure ctx for your development environment:

# Default setup (generates AGENTS.md for universal compatibility):
ctx setup

# Or agent-specific setup:
ctx setup claude        # Claude Code/Desktop  
ctx setup cursor        # Cursor IDE
ctx setup aider         # Aider
ctx setup augmentcode   # Augment Code
ctx setup windsurf      # Windsurf IDE
ctx setup jetbrains     # JetBrains AI Assistant
ctx setup vscode        # VS Code with GitHub Copilot
ctx setup visualstudio  # Visual Studio 2022
ctx setup gemini        # Gemini CLI
ctx setup goose         # Goose AI Agent
ctx setup trae          # Trae IDE
ctx setup opencode      # OpenCode

# See all supported tools:
ctx setup

This creates configuration files that teach your AI assistant to use ctx automatically, enabling token-efficient workflows.

Usage

Simply prefix any command you want to enrich with ctx.

# Basic command
ctx ls -la

# Database query with a specific tokenizer
ctx --token-model openai psql -c "SELECT id FROM users LIMIT 10"

# Pipeline: filter data before tokenizing
ctx cat large.json | jq .items[0:5]

# AI Agent workflow: generate a commit message
ctx git diff --staged | claude -p 'Generate a conventional commit message.'

AI Assistant Setup

ctx supports major AI agents and agentic IDEs, making it easy to integrate token-aware command execution into your existing AI-powered development workflow. With support for 10+ popular tools, you can teach your AI coding assistant to use ctx automatically.

# Default: Set up AGENTS.md (universal format for multiple agents)
ctx setup

# Or set up a specific AI tool:
ctx setup claude        # Explicit Claude Code setup
ctx setup cursor        # Cursor IDE
ctx setup aider         # Aider
[...]

These commands create local configuration files that instruct your IDE's AI to wrap shell commands with ctx, promoting token-efficient workflows.

About AGENTS.md: The AGENTS.md format is an open standard supported by OpenAI Codex, Cursor, RooCode, and many other agents. It provides a standardized way to give instructions to AI coding assistants, making your setup portable across different tools.

Coming Soon: ctx Pro

ctx Pro enhances your ctx experience with powerful analytics and team collaboration features for just $10/agent/month.

• Web Dashboard: Access a comprehensive dashboard to visualize your command-line usage patterns, most frequently used tools, and command history analytics.
• Usage Insights: Discover which tools consume the most tokens, identify optimization opportunities, and track your token savings over time.
• Team Features: Centralized policies, audit logs, and shared configurations for teams to maintain consistency across development workflows.
• Support Open Source: Your subscription directly supports the continued development and maintenance of the ctx project, ensuring regular updates and new features.

Pro features will activate with ctx login. Learn More About Pro Pricing.

Configuration

ctx is configured via CLI flags, environment variables, or a ~/.config/ctx/config.yaml file.

Timeout Behavior

ctx properly terminates entire process trees when timeouts occur, including all child processes spawned by build tools, language runtimes, and shell scripts.

Examples

# Terminates after 2 seconds (including child processes)
ctx --timeout 2s -- go run main.go      # Go compilation + execution
ctx --timeout 2s -- cargo run           # Rust build + run
ctx --timeout 2s -- npm run dev         # Node.js dev server
ctx --timeout 2s -- bash script.sh      # Shell script + subprocesses

# Default timeout is 2 minutes
ctx -- docker build .

# Custom grace period for cleanup
CTX_WAIT_DELAY=5s ctx --timeout 10s -- docker-compose up

Development

Building from Source

Local Development Build:

git clone https://github.com/slavakurilyak/ctx.git
cd ctx
go build -o ctx        # Creates ./ctx binary for testing
./ctx version          # Test local build

Global Installation:

go install .           # Install to $GOPATH/bin (usually ~/bin or ~/go/bin)
ctx version            # Test global installation

Understanding go build vs go install:

Contributing

Contributions are welcome! Please see the Issues page for areas where help is needed.

Resources

• Announcement Blog: Read the announcement of ctx
• Repository: https://github.com/slavakurilyak/ctx
• Issues: https://github.com/slavakurilyak/ctx/issues
• Versioning: docs/VERSIONING.md

Acknowledgments

• Anthropic for pioneering token-efficient tool use
• The creators of countless open-source CLI tools

License

This project is licensed under the MIT License.