📖 What is Auto-Context?

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

It transforms how AI agents interact with your codebase by replacing raw, token-burning context dumps with an intelligent, self-guiding 360° End-to-End Execution Pipeline.

🛑 The Problems It Solves:

• Context Window Pollution & Token Burn: Dumping entire directories, database schemas, and 500 lines of error logs into monolithic context files burns 10,000+ tokens on every single prompt, degrading AI reasoning and triggering premature context compaction.
• Context Drift & AI Amnesia: When opening a new chat session or switching agents, the AI forgets architectural invariants, local port bindings, and coding conventions unless repeatedly reminded.
• Lack of Execution Discipline: Unassisted AI assistants frequently jump straight into writing code without verifying project scope, hallucinate completion without running automated tests, or repeat previously resolved bugs.

⚙️ How Auto-Context Works

Auto-Context establishes a deterministic, multi-phase execution loop that every AI assistant executes automatically from the very first turn:

┌────────────────────────────────────────────────────────┐
│ Phase 0: Scope & Gatekeeper (.agents/project-goal.md)   │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│ Phase 1: Constitutional Guardrails (.agents/rules/)    │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│ Phase 2: Macro Context (.agents/context.md)            │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│ Phase 3: Targeted Discovery (.agents/context/*.md)     │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│ Phase 4: Implementation (.agents/skills/)              │◄──────┐
└──────────────────────────┬─────────────────────────────┘       │
                           ▼                                     │ (Test Failed:
┌────────────────────────────────────────────────────────┐       │  Self-Correct)
│ Phase 5: Verification & Sync Gate                      │       │
│          • Automated Tests (Exit Code 0)               ├───────┘
│          • Sync Invariants & README (Pass)             │
└────────────────────────────────────────────────────────┘

The 6-Phase Autonomous Execution Pipeline

1. Phase 0: Scope & Gatekeeper (.agents/project-goal.md)

   • Autonomous Synthesis: On first run, the AI automatically inspects your repository and populates the project goal, core purpose, active milestones, and anti-goals (what not to build).
   • Context Pruning: If the project is a CLI, library, or script, it automatically prunes non-existent network ports and DB tables from context.md.
   • The Brutal Truth Filter: The AI actively challenges inefficient, over-complicated, or out-of-scope requests before writing code.

2. Phase 1: Constitutional Guardrails (.agents/rules/*.md)

   • Continuous Compliance: Standing, non-negotiable boundaries enforced on every turn (zero hardcoded secrets, early returns, clean git commits, documentation parity).
   • Dynamic Discovery: Any rule created via init-context rule or synced from Central Memory is instantly recognized and enforced without manual config.

3. Phase 2: Macro Context Hub (.agents/context.md)

   • Strict Token Budget (< 80 lines / ~400 tokens): Serves as an executive routing index containing the project archetype, active runtime toolchain, verified runbook commands (build, lint, test), and failure invariants.

4. Phase 3: Targeted Discovery & Precision Reads

   • Zero Bulk Reading: Prohibits dumping 50+ files into context. Follows the precision formula (reading targeted line ranges like #L30-L70): $$\text{Precision Context} = \text{Macro Route Map} + \text{Grep / Symbol Search} + \text{Targeted Range Read}$$
   • Specialised satellites (routes.md, schema.md) are loaded strictly on-demand when relevant.

5. Phase 4: Dynamic Skills Execution (.agents/skills/*/SKILL.md)

   • On-Demand Procedural Runbooks: Reusable operational workflows (Docker ops, Git releases, Browser automation, Server diagnostics) that activate only when their declared triggers match the task.

6. Phase 5: Verification & Self-Correction Gate

   • Automated Verification: The AI runs repository test commands and enforces Exit Code 0.
   • Self-Correction Feedback Loop: If any test fails, completion is blocked—the agent automatically loops back to Phase 4, diagnoses the root cause, applies fixes, and re-verifies until all tests pass.
   • State & Invariants Sync: Upon passing, newly discovered architecture invariants are recorded in context.md, and any modified CLI flags or APIs are synchronized into README.md.

⚡ Fast-Track Exception: For read-only explanations or trivial single-file edits under 10 lines (without architectural impact), the AI skips Phases 0, 2, and 3, jumping straight to Phase 1 guardrails and targeted verification.

⚡ 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 Hub & Satellite architecture powered by progressive disclosure:

your-project/
├── .agents/
│   ├── context.md                <─── Executive Context Hub (Compact macro routing & invariants)
│   ├── project-goal.md           <─── North Star, active milestones, anti-goals & ADRs
│   ├── context/                  <─── Stack-Adaptive Satellites (Loaded on-demand)
│   │   ├── routes.md             (API Endpoints & UI Page Map — loaded for route tasks)
│   │   └── schema.md             (Database Schemas & Models — loaded for DB tasks)
│   ├── rules/                    <─── Domain Rules (Continuous constitutional guardrails)
│   │   ├── code-standards.md     (Clean code, defensive patterns, mandatory feature tests)
│   │   ├── security-boundaries.md(Zero secret leakage, sandbox boundaries)
│   │   └── readme-docs-sync.md   (Mandatory documentation & CLI sync)
│   └── skills/                   <─── Operational Skills (On-demand procedural runbooks)
│       ├── auto-context/         (Context maintenance, memory sync & promotion SOPs)
│       ├── docker-ops/           (Multi-stage containerization & compose management)
│       ├── git-workflow/         (Conventional commits, branch safety & releases)
│       └── feature-verification/ (Structured test execution & verification reporting)
├── AGENTS.md                     <─── Universal standing instructions (Core Execution Loop)
└── GEMINI.md                     <─── Antigravity / Gemini standing instructions

How the Hub & Satellite Pattern Works:

1. The Executive Hub (.agents/context.md):
   • Strict Token Budget (< 80 lines / ~400 tokens): Never allows unbounded bloat. Contains only high-level macro metadata: Project Archetype, runtime toolchains, standardized operations commands (build, lint, test, run), and active failure invariants.
   • Archetype-Adaptive: Automatically marks network tables as N/A for CLI and library projects, keeping the base token footprint minimal.
2. The North Star & Scope Gatekeeper (.agents/project-goal.md):
   • Outlines the core mission, immediate priorities, out-of-scope boundaries (anti-goals), and architectural decision records (ADRs).
   • Serves as the first gate (Phase 0) before any code is written.
3. Adaptive Satellites (.agents/context/*.md):
   • Deep-domain maps (e.g. routes.md for web endpoints, schema.md for ORMs and databases).
   • Progressive Disclosure: Kept completely out of the default prompt context. The AI reads them only when the active prompt specifically targets that domain, saving 80%+ tokens per turn.
4. Strict Idempotency Proof ($f(f(x)) = f(x)$):
   • Running context sync or generation commands 1 time or 100 times produces the exact same deterministic state.
   • User-written custom rules, manual edits outside anchored blocks, and .env secrets remain 100% untouched.

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!
• Active Invariants Over Dead Logs: Auto-Context replaces dead bug logs with high-density technical invariants directly inside .agents/context.md (Section 3: 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 strict Single Source of Truth (SSOT) design. There are zero duplicate directories between the CLI package and Antigravity plugins—all templates, rules, and skills originate from src/auto_context/templates/:

auto-context/
├── .github/
│   └── workflows/
│       ├── release.yml              # Automated PyPI OIDC & GitHub Release on v* tags
│       └── test.yml                 # Multi-platform CI testing matrix (Linux, Windows, macOS)
├── src/
│   └── auto_context/
│       ├── __init__.py              # Package version & UTF-8 stream initialization
│       ├── main.py                  # Root CLI entrypoint & subcommand dispatcher
│       ├── config.py                # Global paths (~/.auto-context, ~/.gemini) & indicators
│       ├── security.py              # Zero-Bypass secret scanner (<10MB guard & key auditor)
│       ├── commands/
│       │   ├── init_cmd.py          # Scaffolding, stack detector, rule, skill & promote
│       │   ├── memory.py            # Central private git repo brain management & harvester
│       │   ├── mcp.py               # Native JSON MCP registry with .bak corruption recovery
│       │   ├── share.py             # Granular Gist publishing via gh CLI / REST API fallback
│       │   ├── import_cmd.py        # Remote Gist/URL importer with collision guard
│       │   └── update_cmd.py        # Modular updater & plugin asset synchronizer
│       └── templates/               # 🌟 CANONICAL SINGLE SOURCE OF TRUTH (SSOT)
│           ├── plugin.json          # Antigravity plugin manifest (v1.5.1)
│           ├── AGENTS.template.md   # Universal standing instructions & Core Execution Loop
│           ├── context.template.md  # Executive Context Hub (<80 lines) & failure invariants
│           ├── project-goal.template.md # North Star, active milestones, anti-goals & ADR
│           ├── rule.template.md     # Domain rule scaffold template
│           ├── skill.template.md    # Operational skill scaffold template
│           ├── profile.template.md  # Central memory developer profile scaffold
│           ├── mcp_config.template.json # Stdio/remote MCP server registry stub
│           ├── rules/               # Canonical domain rules
│           │   ├── code-standards.md      (Clean code, defensive patterns & test mandate)
│           │   ├── security-boundaries.md (Zero secret leakage & sandbox boundaries)
│           │   ├── readme-docs-sync.md    (Mandatory documentation & CLI sync)
│           │   └── registry.json          (Instant collision detection & domain index)
│           └── skills/              # Canonical operational skills
│               ├── auto-context/          (Context maintenance, memory sync & promotion)
│               ├── browser-testing/       (Automated web UI & endpoint verification)
│               ├── docker-ops/            (Multi-stage containerization & compose SOPs)
│               ├── feature-verification/  (Structured test execution & verification report)
│               ├── git-workflow/          (Conventional commits, branch safety & releases)
│               └── server-diagnostics/    (System health, RAM/CPU & open port diagnostics)
├── tests/                           # Complete test suite (27 tests across 8 suites)
│   ├── run_tests.py                 # Zero-dependency test runner with rich terminal reporting
│   ├── test_idempotency.py          # Deterministic re-run & zero-drift verification
│   ├── test_init.py                 # Scaffolding, rule append & promotion verification
│   ├── test_mcp.py                  # Presets, JSON persistence & .env placeholder tests
│   ├── test_memory.py               # Central memory git lifecycle & reset tests
│   ├── test_security.py             # Secret patterns, prohibited extensions & ignore checks
│   ├── test_sharing.py              # Frontmatter detection, Gist URL resolution & item finding
│   ├── test_ssot.py                 # Single source of truth & zero unrendered {{...}} placeholders
│   └── test_update.py               # Semantic version parsing & non-breaking update safety
├── install.ps1                      # 1-Click universal installer (Windows PowerShell)
├── install.sh                       # 1-Click universal installer (Linux / WSL2 / macOS)
├── setup.bat                        # Double-clickable Windows setup helper
├── uninstall.ps1                    # Clean uninstaller for Windows
├── uninstall.sh                     # Clean uninstaller for POSIX
├── pyproject.toml                   # Modern PEP 517/621 package build configuration
├── LICENSE                          # MIT License
└── README.md                        # Documentation & Complete Runbook

Architectural Principles

1. Single Source of Truth (SSOT):
   • The CLI package and global Antigravity plugins share the exact same template files inside src/auto_context/templates/. Assets are never duplicated across directories.
2. Zero-Bypass Security Gate:
   • security.py acts as a strict firewall: private keys, API tokens (sk-..., AIza..., ghp_...), and prohibited sensitive files (.env, .pem) are audited and blocked before any git commit, push, or Gist sharing operation.
3. Idempotent Scaffolding ($f(f(x)) = f(x)$):
   • Running init-context once or 100 times produces the exact same deterministic output. Custom user notes and rules outside anchored blocks remain completely intact.

🤖 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!