compass

Overview
compass serves as a local-first configuration layer for AI coding agents like Claude Code, Codex, and Gemini. Its primary goal is to provide a safety net by preventing unnecessary budget expenditure, blocking risky commands, and ensuring that only verified code is merged. With features such as budget caps, stringent guardrails, and a focused configuration, compass enhances the reliability and safety of AI-driven programming tasks.

Key Features

• Guardrails: A robust system protecting against catastrophic commands and unauthorized actions. It guarantees safety by blocking harmful operations before execution.
• Cost Control: Users can establish a dollar limit that halts sessions once reached, safeguarding against unexpected overspending.
• Self-Healing Pull Requests: When a pull request is submitted, compass autonomously reviews, audits, and proposes necessary changes until the PR meets predefined quality benchmarks, allowing for a smooth merging process.
• No External Telemetry: compass operates entirely offline, ensuring user privacy and eliminating concerns associated with unauthorized data transmission.
• Flexible Configuration: Users can customize the settings to align with their specific development needs while ensuring consistent, reliable behavior across different environments.

Installation Instructions

Installation is straightforward and reversible, allowing users to incorporate compass without any complicated systems. Users have multiple methods for installation, including:

# Clone the repository and run the quickstart
git clone https://github.com/dshakes/compass ~/compass && cd ~/compass && ./quickstart.sh

For those using Claude Code, installing via the plugin marketplace is also an option:

/plugin marketplace add dshakes/compass

/plugin install core@compass

Example Usage

Start by defining your budget cap to manage spending effectively:

export COMPASS_MAX_USD=5  # Sets the maximum spend to $5

Then run operations within the agent, and compass will enforce budget limits accordingly. It proactively prevents commands that may exceed the set financial threshold, eliminating the risk of unexpected costs during development.

The Loop Workflow

The loop mechanism in compass iteratively processes tasks, enhancing code quality through continuous evaluation, critique, modification, and retrial. Each iteration produces tested outcomes before final merging, ensuring that stakeholders remain in control:

1. Generate code
2. Test outcomes
3. Critique findings
4. Fix issues
5. Repeat until criteria are met

Conclusion

compass not only streamlines the coding process but enhances it by embedding safeguards against common pitfalls associated with AI-assisted programming. It emphasizes responsible cost management, security, and development integrity, making it an essential tool for developers looking to effectively harness their AI coding agents.