PACKAGE EXPLORERView in registry

ai-guider

PyPI

Local-first MCP server for AI agent guidance and mission governance

Versions collected1

Direct dependencies8From release 1.0.1

Last observed21 Oct, 10:51 UTC

README

Version 1.0.1 documentation

AI Guider

A local co-pilot for AI coding agents.

AI Guider does not write your code. It sits beside agents (Cursor, Claude, Codex, and others) and helps them stay on track: clarify what you want, block out-of-scope work, and finish cleanly.

You → Cursor / Claude / Codex → AI Guider (local) → decisions, maps, and guardrails

Everything stays on your machine. No cloud account required for Guider itself.

What you get

Capability	In plain terms
Missions	A clear objective, success criteria, and open questions
Q&A gate	The agent must ask you before guessing (stack, storage, etc.)
Plan refine	Sharpens a plan from your answers — does not invent features
Scope checks	Approve / caution / reject before risky changes
Codebase map	Quick map of folders, entrypoints, and key symbols
Hooks (Cursor)	Optional: block file edits until Guider approves the action

Install in 5 minutes

Requirements

macOS, Linux, or Windows
Python 3.10 or newer (3.12 recommended)

Step 1 — Install AI Guider

cd ~/ai-guider          # or wherever you cloned this repo
python3.12 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Check that it works:

ai-guider doctor

Step 2 — Connect your AI tools

Pick one command:

# Recommended: connect everything you use
ai-guider init --all-clients

# Or only what you need
ai-guider init --cursor --hooks     # Cursor + edit guardrails
ai-guider init --claude             # Claude Code
ai-guider init --claude-desktop     # Claude Desktop app
ai-guider init --codex              # OpenAI Codex

Step 3 — Restart the client

Tool	What to do
Cursor	Reload window (`Cmd+Shift+P` → “Developer: Reload Window”)
Claude Code	Start a new session
Claude Desktop	Quit completely, then reopen
Codex	Restart; run `codex mcp list` and look for `ai-guider`

Full details: Installation guide · Connect Claude & Codex

How to use it (everyday flow)

You do not need to memorize tool names. Tell your agent:

Use AI Guider to govern this request:
Build a simple todo webapp, local only, no backend.

A well-behaved agent will roughly:

Start a mission and ask you any missing questions
Record your answers
Refine and approve a plan
Check scope before editing files
Mark success criteria done, then complete

Step-by-step with examples: Usage guide

Useful commands

ai-guider --version       # Installed version
ai-guider help            # Full command guide (what each command does)
ai-guider doctor          # Is my install healthy?
ai-guider bootstrap       # Show active mission + tips for this session
ai-guider map             # Print a map of the current project
ai-guider resume          # What mission is active?
ai-guider missions        # List recent missions
ai-guider report          # Governance summary
ai-guider templates       # Mission templates (personal site, API, …)

Documentation

Browse all guides: docs/

Guide	Audience
Installation	First-time setup, troubleshooting
Usage	Day-to-day workflow in plain language
Clients (Cursor, Claude, Codex)	Per-app connection steps
Cursor deep dive	Hooks, maps, Cursor-only features
Publishing to PyPI	GitHub Release → PyPI workflow

License

MIT

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Versions 1

Collected releases

Version	Published	Direct dependencies	Open version
1.0.1	12 Jul 2026	8

Package advisories

No matching advisories collected

This describes our collected data; it is not a security assessment.

Metadata history

Meaningful changes

Current collected state Current

Observed since 21 Oct, 10:51 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package:cbeae12a8103db9850db40e54acd7ad17312ac5bc5ece10b2a280f7550bc22c0