GuideAI — The Behavior Engine for AI Agents

Turn your LLM chains-of-thought into a reusable procedural handbook — cut reasoning tokens by up to 46% while maintaining or improving quality.

GuideAI captures recurring AI reasoning patterns as named behaviors and conditions agents to reuse them, inspired by Meta AI's Metacognitive Reuse research.

Get Started in 30 Seconds

Cloud — zero install:

→ https://amprealize.ai (sign up and go)

CLI — for developers:

pipx install guideai
guideai init

Desktop app: not shipped from this repository yet; use the cloud console, CLI, VS Code extension, or MCP today. Watch GitHub Releases for future desktop builds.

What Is GuideAI?

GuideAI is a behavior-driven AI workflow platform that extracts, stores, and retrieves procedural knowledge — reusable how-to strategies — from successful AI reasoning traces. Instead of re-deriving common patterns on every prompt, agents consult a behavior handbook and allocate their compute budget to novel subproblems.

The platform serves three roles:

• Student — consumes behaviors in-context for efficient task execution
• Teacher — validates behaviors, creates examples, and reviews quality
• Metacognitive Strategist — discovers patterns, proposes new behaviors, and curates the handbook

GuideAI works across multiple surfaces: Web Console, CLI, VS Code Extension, and MCP Server — with consistent behavior retrieval and execution tracking everywhere.

Features

• Behavior Engine — extract, version, retrieve, and apply reusable reasoning patterns
• MCP Server — 220+ tools for behaviors, runs, compliance, actions, metrics, and more
• Multi-Surface Parity — CLI, REST API, MCP, Web UI, and VS Code extension share the same backend
• Agent Orchestration — run agents with behavior-conditioned inference (BCI) for token-efficient execution
• Compliance & Audit — full action logging, hash-chained audit trails, and policy enforcement
• Structured Logging (Raze) — centralized, queryable, context-enriched telemetry
• Environment Management (Amprealize) — blueprint-driven container orchestration with compliance hooks
• Multi-Tenant — org-scoped or personal projects with role-based access control
• OAuth & Device Flow Auth — GitHub, Google, Microsoft providers with token vault
• Billing Tiers — OSS → Starter → Pro → Team → Enterprise

Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Web Console │  │  VS Code    │  │    CLI      │
│  (React)     │  │  Extension  │  │  (Click)    │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┴────────┬────────┘
                                  │
                         ┌────────▼────────┐
                         │   FastAPI + MCP  │
                         │   Server         │
                         └────────┬────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
  ┌──────▼──────┐  ┌──────────────▼──────────────┐  ┌─────▼──────┐
  │  Behavior   │  │  RunService / ActionService  │  │  Raze      │
  │  Service    │  │  ComplianceService           │  │  Telemetry │
  └─────────────┘  └─────────────────────────────┘  └────────────┘

Project Structure

guideai/
├── guideai/              # Core Python package
│   ├── mcp_tool_manifests/  # Bundled MCP tool JSON (sync from mcp/tools for releases)
│   ├── behaviors/        # Behavior engine
│   ├── mcp/              # MCP server (220+ tools)
│   ├── services/         # Run, Action, Compliance services
│   ├── auth/             # OAuth, device flow, token vault
│   ├── cli/              # CLI commands (Click)
│   ├── config/           # Configuration loader
│   └── storage/          # Storage adapters (SQLite, Postgres)
├── packages/
│   ├── raze/             # Structured logging (standalone)
│   ├── amprealize/       # Environment orchestration (standalone)
│   ├── midnighter/       # Background task scheduler
│   ├── notify/           # Notification service
│   ├── observability/    # Metrics pipeline
│   └── billing/          # Billing & tier management
├── web-console/          # React web UI
├── extension/            # VS Code extension
├── dashboard/            # Grafana metrics dashboard
├── docs/
│   ├── contracts/        # Service contract specs
│   ├── agents/           # Agent role documentation
│   └── research/         # Research papers & references
├── infra/                # Docker, deployment, CI/CD configs
├── tests/                # Test suite
├── scripts/              # Dev & CI scripts
├── mcp/                  # MCP tool JSON schemas
├── migrations/           # Alembic database migrations
└── schema/               # Database schema definitions

Documentation

OSS install profiles

Development

# Clone and set up
git clone https://github.com/SandRiseStudio/guideai.git
cd guideai
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Install pre-commit hooks
./scripts/install_hooks.sh

# Run tests
pytest

# Generate local MCP configs for VS Code/Cursor/Claude/Codex and smoke-test them
guideai mcp-server init
guideai mcp-server doctor

# Keep GUIDEAI_* runtime settings in .env / .env.local / .env.mcp
# instead of embedding DSNs into editor MCP configs

# Start the server
uvicorn guideai.api:app --reload

# Run secret scan
bash scripts/scan_secrets.sh

Contributing

See CONTRIBUTING.md for development setup, PR process, commit conventions, and the behavior handbook reference.

Please read our Code of Conduct before contributing.

Security

To report security vulnerabilities, please see SECURITY.md. Do NOT use GitHub Issues for security reports.

Canonical GitHub repository

Public source of truth: github.com/SandRiseStudio/guideai.

Maintainers (after org or repo moves): point PyPI Trusted Publishing at SandRiseStudio/guideai, confirm GitHub Actions secrets and environments still apply to this repository, and re-check branch protection and Dependabot on the default branch.

License

Apache License 2.0

Copyright 2026 GuideAI Team