Full Setup (Advanced)

Most users want maina setup instead

The one-command wizard (Getting Started) covers 95% of what this page documents — in under 60 seconds, anonymously, with a tailored constitution and agent files. Read on only if you need the lower-level primitives (maina init, manual MCP wiring, custom CI plumbing).

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 + package manager, installs maina globally, and runs maina setup in the current repo. Exits with a shell-profile-specific remediation if maina doesn’t land on PATH afterwards. See Getting Started.

bun (global)

bun add -g @mainahq/cli
maina setup

pnpm (global)

pnpm add -g @mainahq/cli
maina setup

npm (global)

npm install -g @mainahq/cli
maina setup

bunx (one-off)

bunx @mainahq/cli@latest setup

Runs the wizard from a cached copy. Setup warns that maina may not be on PATH after exit (unless you already had it installed globally), so AI-agent subshells may not find it — prefer one of the global install paths above when you want a permanent install.

Tip

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

Quick Start

1. Initialize your project

   maina setup          # recommended — one command
   # or, if you prefer the lower-level primitives:
   maina init --install # detects stack, installs verification tools

   maina setup is the zero-friction wizard. maina init is the lower-level bootstrap it delegates to; it remains available for scripting and snapshot tests.

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

maina setup wires this automatically for every AI coding tool it detects. Manual reference:

Claude Code

Automatic — setup writes .claude/CLAUDE.md and configures MCP.

Cursor

Automatic — setup writes .cursor/rules/maina.mdc and .mcp.json.

Windsurf

Automatic — setup writes .windsurf/rules/maina.md and configures ~/.codeium/windsurf/mcp_config.json.

Other

{"mcpServers":{"maina":{"command":"bunx","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