📖 What is Auto-Context?

Auto-Context is an autonomous context orchestration and instruction management protocol for AI coding assistants (Antigravity, Cursor, Claude Code, Copilot, Windsurf).

The Problem It Solves:

• Context Bloat: Dumping entire codebases, database schemas, and 500 lines of error logs into a giant context file burns 10,000+ tokens on every single prompt.
• AI Amnesia: When you switch sessions or start a new chat, the AI forgets architectural invariants, port setups, and coding guidelines unless repeatedly reminded.

How Auto-Context Works (The 3 Context Tiers):

1. Executive Hub (.agents/context.md): A lightweight macro routing index loaded at session boot so the AI immediately knows your active stack, ports, and operations runbook without burning tokens.
2. Continuous Rules (.agents/rules/ & AGENTS.md): Standing guardrails injected into the prompt context on every chat turn to enforce security boundaries, clean code standards, and doc sync.
3. Adaptive Satellites & Skills (.agents/context/ & .agents/skills/): Loaded on-demand only when a task requires them (e.g. database schema migrations, route implementations, or Docker deployments).

⚡ Quick Install

Install directly via PyPI or using our 1-click native installer:

📦 Direct via PyPI (Universal - Windows, macOS, Linux, WSL2):

# Recommended via uv (fast & isolated):
uv tool install auto-context-cli

# Or via standard pip:
pip install auto-context-cli

# Or via pipx:
pipx install auto-context-cli

🪟 Windows (PowerShell 1-Click Installer):

irm https://raw.githubusercontent.com/Cyber-arghya/auto-context/main/install.ps1 | iex

🐧 Linux / WSL2 / macOS (Bash / Zsh 1-Click Installer):

curl -sSL https://raw.githubusercontent.com/Cyber-arghya/auto-context/main/install.sh | bash

Note: The installer automatically provisions init-context in your PATH and configures the global Antigravity AI Agent Plugin at ~/.gemini/config/plugins/auto-context/.

💡 Core Philosophy

1. Hub & Satellite Context Architecture

Dumping routes, schemas, credentials, and runbooks into a single monolithic context file burns thousands of tokens every single turn. Auto-Context enforces a clean, modular structure:

your-project/
├── .agents/
│   ├── context.md                <─── Executive Context Hub (Compact system routing)
│   ├── project-goal.md           <─── North Star, goals & ADR
│   ├── context/                  <─── Adaptive Satellites (Loaded on-demand)
│   │   ├── gotchas.md            (Architecture Invariants, Port Traps & Edge Cases)
│   │   ├── routes.md             (API Endpoints & UI Page Map — loaded for route tasks)
│   │   └── schema.md             (Database Schemas & Models — loaded for DB tasks)
│   ├── rules/                    <─── Domain Rules (Continuous guardrails)
│   └── skills/                   <─── Operational Skills (On-demand procedural runbooks)
├── AGENTS.md                     <─── Universal standing instructions
└── GEMINI.md                     <─── Antigravity / Gemini standing instructions

2. Zero Dead Logs & The Brutal Truth Filter

• Zero Bug Diaries: Chronological diaries of trivial solved bugs waste context tokens. Git history already records past commits!
• Gotchas Over History: Auto-Context replaces bug logs with high-density technical invariants in .agents/context/gotchas.md (non-obvious architecture traps, port collisions, and constraints that cannot be guessed from reading code).

3. Rule vs. Skill: The Boundary

🚀 Complete CLI Command Runbook

All commands support both modern subcommands (init-context <command>) and legacy flags.

1. Initialize Context Tracking

Scaffolds the complete .agents/ context hub, standing rules, starter domain rules, and built-in skills.

# Initialize active workspace
init-context

# Initialize a specific directory
init-context /path/to/project

# Explicit subcommand syntax
init-context init [DIR]

2. Rule Management (rule)

Scaffolds a new domain rule or appends guidelines to an existing domain with built-in duplicate detection (registry.json).

# Create local project rule (.agents/rules/api-standards.md)
init-context rule api-standards
init-context -r api-standards

# Append guideline to an existing rule
init-context rule code-standards --append --guideline "Always use early returns"
init-context -r code-standards -a --guideline "Enforce static typing"

# Create global rule across all projects (~/.gemini/config/plugins/auto-context/rules/)
init-context rule security-policies --global
init-context -r security-policies -g

# Overwrite existing rule
init-context rule api-standards --force

3. Skill Management (skill)

Scaffolds a new operational skill directory with frontmatter triggers, description, and procedure runbook.

# Create local project skill (.agents/skills/deploy-k8s/SKILL.md)
init-context skill deploy-k8s
init-context -s deploy-k8s

# Create global skill across all projects
init-context skill cloudflare-worker --global
init-context -s cloudflare-worker -g

# Overwrite existing skill
init-context skill deploy-k8s --force

4. Rule & Skill Promotion (promote)

Promotes a local workspace rule or skill to machine-wide Global Plugin scope and pushes it to Central Memory in one step.

# Promote local rule to global scope
init-context promote api-standards

# Promote local skill to global scope
init-context promote deploy-k8s

5. Central Memory Brain (memory)

Manage your private central memory repository (dotfiles for AI agents) across multiple machines.

# 1. Initialize private GitHub memory repository
init-context memory init
init-context memory init --repo-name my-agent-brain --private

# 2. Push workspace rules & skills (runs automated Zero-Bypass secret audit before push)
init-context memory push
init-context memory push --message "feat: add payment gateway rules"

# 3. Pull central brain on a new machine
init-context memory pull
init-context memory pull --url git@github.com:username/my-agent-brain.git

# 4. Inspect memory status & sync health
init-context memory status

# 5. Switch or configure remote repository
init-context memory remote
init-context memory remote git@github.com:username/new-memory-brain.git

# 6. Reset local memory cache
init-context memory reset
init-context memory reset --force

6. MCP (Model Context Protocol) Registry (mcp)

Manage native MCP server configurations for Antigravity and Gemini CLI without committing plaintext secrets.

# 1. Add pre-configured presets (references ${ENV_VARS} safely)
init-context mcp add sqlite --args "data.db"
init-context mcp add postgres
init-context mcp add github
init-context mcp add brave
init-context mcp add duckdb
init-context mcp add time
init-context mcp add git

# Customize secret environment variable name
init-context mcp add github --env-var MY_GITHUB_PAT

# 2. Add custom command or remote HTTP MCP tool
init-context mcp add my-tool --command "python" --args "server.py"
init-context mcp add remote-tool --url "https://mcp.example.com/sse"

# 3. Choose runner explicitly (uvx vs npx)
init-context mcp add fetch --runtime uvx
init-context mcp add puppeteer --runtime npx

# 4. List registered MCP servers
init-context mcp list
init-context mcp list --global

# 5. Remove an MCP tool
init-context mcp remove sqlite
init-context mcp remove github --global

# Legacy flag aliases:
init-context --add-mcp sqlite
init-context --list-mcp
init-context --remove-mcp sqlite

7. Granular Sharing & Import (share / import)

Share isolated rules or skills with teammates via GitHub Gist and import them safely with Collision Guard.

# 1. Share a rule or skill as a private GitHub Gist
init-context share docker-ops
init-context share code-standards

# Share as public Gist
init-context share docker-ops --public

# 2. Import rule or skill from Gist / URL
init-context import https://gist.github.com/user/gist_id

# Import into machine-wide global plugin scope
init-context import <gist-url> --global

# Import with a custom local name
init-context import <gist-url> --as custom-docker-skill

8. Modular Updates (update)

Safely update the CLI package and sync global plugin assets without overwriting custom user rules or project context.

# Run modular update (checks PyPI/GitHub and updates plugin assets)
init-context update

# Check for updates without applying
init-context update --check

# Force refresh of all global plugin definitions
init-context update --force

9. Global Command Flags

📁 Generated Project Layout

Running init-context inside any project establishes a clean 5-tier architecture:

📦 Repository Architecture

Auto-Context uses a Single Source of Truth (SSOT) design with zero duplicate directories:

auto-context/
├── pyproject.toml                   # Modern PEP 517/621 package configuration
├── src/
│   └── auto_context/
│       ├── __init__.py
│       ├── main.py                  # Root CLI entrypoint & flag router
│       ├── config.py                # Centralized paths (~/.auto-context, ~/.gemini)
│       ├── security.py              # Zero-Bypass secret scanner & credential auditor
│       ├── commands/
│       │   ├── init_cmd.py          # Project scaffolding & rule/skill creation
│       │   ├── memory.py            # Central private git repo brain management
│       │   ├── mcp.py               # Native JSON MCP registry & runner selector
│       │   ├── share.py             # Granular Gist publishing via gh / httpx
│       │   ├── import_cmd.py        # Remote URL / Gist import & collision guard
│       │   └── update_cmd.py        # Modular updater & plugin asset synchronizer
│       └── templates/               # 🌟 CANONICAL SINGLE SOURCE OF TRUTH
│           ├── plugin.json          # Antigravity plugin manifest
│           ├── rules/               # Canonical domain rules (code-standards, security, etc.)
│           ├── skills/              # Canonical skills (docker-ops, git-workflow, etc.)
│           └── *.template.md        # Core scaffolds (AGENTS, context, project-goal)
├── tests/                           # Complete automated test suite (22 unit & SSOT tests)
├── install.sh                       # 1-Click universal installer (Linux / WSL2 / macOS)
├── install.ps1                      # 1-Click universal installer (Windows PowerShell)
├── setup.bat                        # Double-clickable Windows setup
├── uninstall.sh                     # Clean uninstaller for POSIX
├── uninstall.ps1                    # Clean uninstaller for Windows
├── LICENSE                          # MIT License
└── README.md                        # Documentation & Runbook

🤖 Supported AI Assistants

• Google Antigravity IDE & CLI (agy) (Native full plugin support)
• Cursor AI (Reads AGENTS.md and .agents/context.md)
• Claude Code / Anthropic Agent
• GitHub Copilot Chat & Workspace
• Windsurf IDE (Codeium)
• Cline / Roo Code

👤 Author

• GitHub: @Cyber-arghya
• Email: work.arghya01@gmail.com

📄 License

This project is open-source and licensed under the MIT License. Contributions and pull requests are warmly welcomed!