Quickstart

Welcome to Midcore. This guide gets you from zero to your first proof-carrying change in a few minutes — either from the web Studio (Intent Wizard) or from the CLI.

Run your first automation in Studio

The fastest path is the Intent Wizard. Open Studio, type one or two sentences about what you want to happen, answer a few short clarifying cards, review the plan, and launch.

You can stop the run at any step, edit the plan, or hand control over to the CLI flow below — they share the same gates and evidence.

Open Studio · How the Intent Wizard works

Before you begin

A code project (or an empty directory) to work with
Terminal or command prompt
For Desktop IDE: download from the Download page.

Accounts

The CLI and VS Code extension can run with a local LLM (offline) or a configured cloud provider. No account is required for offline use. For cloud, configure your provider in .maestro/ or environment variables.

Step 1: Install Midcore

Choose your preferred install method:

macOS, Linux, WSL:

bash

curl -fsSL https://get.midcore.dev/install.sh | bash

Windows PowerShell:

powershell

irm https://get.midcore.dev/install.ps1 | iex

Verify your setup

Run midcore --version — you should see a version number.
Run midcore init in a test directory.
Confirm that .maestro/ exists (intent.yaml, gates.yaml, evidence structure).

Step 2: Initialize a project

In any directory (new or existing repo), run:

bash

cd your-project
midcore init

This creates a .maestro/ directory with intent.yaml, gates.yaml, and the evidence ledger structure.

Step 3: Run your first task

Ask the agent to do something small:

bash

midcore agent "add a README with project name and install instructions"

The agent will parse intent, lock scope, run hardening and gates, and show you proposed changes. Approve or edit as needed.

Common first tasks

Task	Command
First agent task	midcore agent "add a README"
First plan (design only)	midcore plan "refactor auth module"
Run gates	midcore gates run
Ask a question (read-only)	midcore ask "How does the API handle errors?"

Pro tips

Start with additive tasks

Your first runs go smoother with additive tasks (add a file, add a test, add docs). Avoid big refactors or deletions until you're comfortable with the agent loop and gates.

Use Plan for big refactors

For large design or migration work, run midcore plan "…" first. Lock the design and contracts before switching to Agent mode to implement.

Run gates after changes

After the agent (or any manual edit), run midcore gates run to confirm everything still passes. Use it in CI as well.

Step 4: Run gates manually

To run all configured gates without the agent:

bash

midcore gates run

Gates are deterministic checks (tests, lint, contract validation, etc.). See Gates & evidence and Gates reference.

Essential commands

Command	What it does
midcore --version	Check installation
midcore init	Initialize .maestro/ in current directory
midcore agent "task"	Run agent with a one-off task
midcore plan "migration"	Open plan mode for design
midcore gates run	Run all gates

What's next

Learning path — ordered path from Overview to Reference
How Midcore works — agent loop, tools, and gates
Gates & evidence — tiers, ledger, and proof
Common workflows — bugs, refactors, features
Best practices — clear intent, right mode, verify after edit
CLI reference — full command list and exit codes
Troubleshooting — install, auth, gates, and CI

FAQ · Glossary

Run your first automation in Studio

The fastest path is the Intent Wizard. Open Studio, type one or two sentences about what you want to happen, answer a few short clarifying cards, review the plan, and launch.

You can stop the run at any step, edit the plan, or hand control over to the CLI flow below — they share the same gates and evidence.

Before you begin

A code project (or an empty directory) to work with

Terminal or command prompt

For Desktop IDE: download from the Download page.

Accounts

Step 1: Install Midcore

Choose your preferred install method:

macOS, Linux, WSL:

bash

curl -fsSL https://get.midcore.dev/install.sh | bash

Windows PowerShell:

powershell

irm https://get.midcore.dev/install.ps1 | iex

Verify your setup

Run midcore --version — you should see a version number.

Run midcore init in a test directory.

Confirm that .maestro/ exists (intent.yaml, gates.yaml, evidence structure).

Task

Command

First agent task

midcore agent "add a README"

First plan (design only)

midcore plan "refactor auth module"

Run gates

midcore gates run

Ask a question (read-only)

midcore ask "How does the API handle errors?"

Pro tips

Start with additive tasks

Your first runs go smoother with additive tasks (add a file, add a test, add docs). Avoid big refactors or deletions until you're comfortable with the agent loop and gates.

Use Plan for big refactors

For large design or migration work, run midcore plan "…" first. Lock the design and contracts before switching to Agent mode to implement.

Run gates after changes

After the agent (or any manual edit), run midcore gates run to confirm everything still passes. Use it in CI as well.

Command

What it does

midcore --version

Check installation

midcore init

Initialize .maestro/ in current directory

midcore agent "task"

Run agent with a one-off task

midcore plan "migration"

Open plan mode for design

midcore gates run

Run all gates

What's next

Learning path — ordered path from Overview to Reference

How Midcore works — agent loop, tools, and gates

Gates & evidence — tiers, ledger, and proof

Common workflows — bugs, refactors, features

Best practices — clear intent, right mode, verify after edit

CLI reference — full command list and exit codes

Troubleshooting — install, auth, gates, and CI