Getting Started
Install aictrl.dev, connect to your AI coding agent, and run your first governed session in under five minutes.
Prerequisites
Before you begin, make sure you have the following:
- Claude Code installed and working (
claude --versionshould return 1.x+) - Node.js 18+ installed (required for the MCP transport layer)
- A Google account for authentication (GitHub SSO coming soon)
Installation
Add aictrl.dev as an MCP server to your Claude Code setup. Run this command in your terminal:
Alternatively, add it manually to your MCP configuration file:
Your First Session
Once installed, start a governed session with your AI agent. Here's a step-by-step walkthrough:
- Open Claude Code in a project directory. aictrl.dev automatically detects the connected MCP server and creates a session context.
- Give your agent a task — for example, "Add input validation to the signup form." The agent will register the task with aictrl.dev and begin tracking progress.
- Watch evidence accumulate — as your agent works, it captures screenshots, test outputs, and commit hashes as evidence. You can review these in the dashboard.
- Review and approve — when the agent completes the task, review the collected evidence and approve or request changes through the aictrl.dev dashboard.
- Ship with confidence — the full audit trail (who did what, when, and why) is preserved for your records. Every change is traceable back to evidence.
Core Concepts
Understanding these five concepts will help you get the most out of aictrl.dev.
Sessions
A session is a bounded unit of work performed by an AI agent. It tracks the full lifecycle from task assignment through evidence collection to human review. Each session has a unique ID, a timeline of events, and a final status (approved, rejected, or expired).
Acceptance Criteria
Acceptance criteria define what "done" looks like for a given task. They are set before the agent begins work and act as a contract between the human reviewer and the AI. The agent must provide evidence for each criterion before the session can be approved.
Evidence
Evidence is proof that work was completed correctly. This includes screenshots of UI changes, test output logs, commit hashes, and any other artifacts the agent produces. Evidence is immutable once captured — it cannot be modified after submission.
Approval Gates
Approval gates are human checkpoints placed at critical moments in a workflow. When an agent reaches a gate, it pauses and waits for human review. Gates can be configured for sensitive operations like database migrations, deployment triggers, or security-critical changes.
Checkpoints
Checkpoints preserve context continuity across sessions. When an agent hits a checkpoint, it saves its current state — progress, decisions made, files modified — so work can resume later without losing context. Useful for long-running features that span multiple sessions.
MCP Configuration
The MCP configuration file controls how your agent connects to aictrl.dev. Here are the available options:
Config File Location
The configuration is stored in your Claude Code MCP settings:
- Global:
~/.claude/mcp.json - Per-project:
.claude/mcp.jsonin your project root
Environment Variables
| Variable | Description | Default |
|---|---|---|
AICTRL_ORG_ID |
Your organization identifier | Auto-detected |
AICTRL_API_KEY |
API key for authentication (optional if using browser auth) | None |
AICTRL_ENVIRONMENT |
Target environment (production or sandbox) |
production |
AICTRL_LOG_LEVEL |
Logging verbosity (debug, info, warn, error) |
info |