Get Started

Quick Start

After install, jump into a project and run minnal. That is the whole onboarding — but here is what to do next.

Launch the TUI

bash

cd path/to/your/project
minnal

On first launch you will be asked to connect a model provider. Use the /connect slash command to log in to Anthropic, OpenAI, Gemini, Copilot, or paste an API key for any other provider.

Initialize the project

Run /init inside a fresh repo. minnal scans the codebase, infers the conventions, and writes an AGENTS.md file at the root that future sessions read automatically.

bash

/init

Ask and build

Once connected, talk to it like a sharp junior engineer:

How is auth wired in @src/api/index.ts? Add a /logout route that
revokes the refresh token, then write a unit test.

Non-interactive runs

bash

minnal run "summarize the last 10 commits in this repo"

Use minnal run in scripts, CI jobs, or git hooks. Output is plain text by default; pass --json for machine-readable output.

Resume a session

Every session gets a memorable name (fox, oak, vega, …). Resume by name from anywhere:

bash

minnal --resume fox

You can also resume sessions from other harnesses — Claude Code, Codex, OpenCode, and pi. minnal will pick up the conversation transcript and continue.

Server mode

bash

# Start the persistent core
minnal serve

# Attach a TUI client
minnal connect

# Attach a second client to the same server
minnal connect

The server keeps memory, sessions, and skill state hot across many attached clients — including remote ones over Tailscale.

Dictation

bash

minnal dictate

Voice input via your configured speech-to-text command. minnal does not bundle an STT engine — bring your own (whisper.cpp, macOS say, etc.).

Next steps

Configure providers in detail — see Providers & OAuth.
Wire up MCP servers and skills.
Try Swarm: spin up two minnals in the same repo.