Getting Started

Maina is the verification layer for AI-generated code. 19+ tools. 7 languages. One command. Zero config.

Install

One-liner (recommended)

curl -fsSL https://api.mainahq.com/install | bash

Detects your OS, installs maina, finds your AI tools, configures MCP automatically.

bun

bun add -g @mainahq/cli

npm

npm install -g @mainahq/cli

Try without installing

npx @mainahq/cli init
npx @mainahq/cli verify

Tip

Prerequisites: Git and Bun (v1.1+) or Node.js (v18+). That’s it.

Quick Start

1. Initialize your project

   maina init --install

   This detects your stack, creates .maina/ with a constitution and custom prompts, and installs missing verification tools.

   Then run guided setup:

   maina setup   # guided setup — detects IDE, configures MCP

2. Make changes and commit

   git add .
   maina commit

   maina commit runs the full 19+ tool verification pipeline — syntax guard, parallel analysis, diff-only filtering — then commits if everything passes.

3. Compile codebase knowledge

   maina wiki init    # compile codebase knowledge
   maina wiki query "how does auth work?"

4. Run verification standalone

   maina verify
   maina verify --deep     # Add AI semantic review
   maina verify --visual   # Add Playwright screenshot regression
   maina verify --cloud    # Submit to Maina Cloud

5. Start a feature with the full workflow

   maina brainstorm        # Explore the idea, create a ticket
   maina plan my-feature   # Create branch with structured spec/plan
   # ... implement ...
   maina commit            # Verify and commit
   maina pr                # Create PR with verification proof

6. Check your setup

   maina doctor

   Shows which of the 19+ tools are installed, engine health, and install commands for anything missing.

Supported Languages

Maina auto-detects your project language and adapts the verification pipeline:

TypeScript

Detected from tsconfig.json. Linter: Biome.

Python

Detected from pyproject.toml, requirements.txt. Linter: ruff.

Go

Detected from go.mod. Linter: go vet.

Rust

Detected from Cargo.toml. Linter: clippy.

C# / .NET

Detected from .sln, .csproj. Linter: dotnet format.

Java / Kotlin

Detected from pom.xml, build.gradle. Linter: Checkstyle.

PHP

Detected from composer.json. Linter: PHPStan, Psalm.

Zero-Friction Layers

Maina works with zero config and scales up as you add capabilities.

Layer	What you add	What you get
L0 — Git-native	Nothing beyond Git + Bun	Core commands, deterministic verification, context engine
L1 — Add AI	MAINA_API_KEY or Ollama	AI-powered reviews, commit messages, explanations, fix generation
L2 — Add tools	Semgrep, Trivy, Secretlint, SonarQube	Deeper SAST, CVE scanning, secret detection, quality gates
L3 — Add PM	GitHub Issues	Sync to Huly, Linear, Plane, or any GitHub-syncing PM tool

Note

No accounts. No Docker. No cloud required. Everything runs locally in your terminal.

What happens during maina commit

1. Syntax guard — Language-aware linting (Biome/ruff/go vet/clippy/dotnet format/Checkstyle/PHPStan). Under 500ms. Rejects immediately on failure.

2. Parallel analysis — 19+ tools run in parallel: slop, Semgrep, Trivy, Secretlint, SonarQube, Stryker, diff-cover, typecheck, consistency, ZAP, Lighthouse, AI review, and more.

3. Diff-only filter — Only findings on changed lines. No pre-existing noise.

4. AI fix (if AI configured) — Context-aware fix suggestions.

5. Git commit — If everything passes, your changes are committed.

6. Workflow tracking — Step recorded in workflow context + async RL feedback for prompt evolution.

MCP Server

Add Maina to your IDE:

Claude Code

Automatic — maina init creates .claude/settings.json

Cursor

Automatic — maina init creates .mcp.json

Windsurf

Run maina setup to configure ~/.codeium/windsurf/mcp_config.json

Other

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

CI Integration

Cloud (no local tools)

- uses: mainahq/maina/.github/actions/verify@main
  with:
    token: ${{ secrets.MAINA_TOKEN }}

Local (on runner)

- uses: mainahq/maina/.github/actions/verify@main
  with:
    base: main

Both options run the full verification pipeline on every PR, posting findings as inline review comments. Exit codes: 0 (passed), 1 (findings), 2 (tool failure), 3 (config error). See the CI Integration docs for full configuration.

Cloud Sync

Share prompts and feedback across your team:

maina login          # authenticate with Maina Cloud
maina sync pull      # get team prompts
maina sync push      # share your prompts

Cloud Verification

Run the full pipeline in the cloud — no local tool installs required:

maina login              # authenticate (one-time)
maina verify --cloud     # submit diff to Maina Cloud

Tip

Results are stored as proof artifacts and returned to your terminal. The same 19+ tools run in the cloud. See Verify Engine — Cloud Verification for details.

Next Steps

Commands All 38+ commands across workflow phases

Wiki Compile codebase knowledge

Configuration Model tiers, constitution, custom prompts

MCP Server Add Maina to your IDE

Engines How Context, Prompt, and Verify work