Set up a project

Minimal reads a single minimal.toml at the root of your repository. It declares where your software comes from, how the project builds, and what every developer’s session gets. Generate a starting point with min init, then enter a session.

Run min init

From your project directory, run:

min init

min init inspects the source tree, detects the stack (Go, Rust, pnpm, npm, Bun, Deno, pip, uv, Gradle, Make, and more), and proposes a minimal.toml, asking for confirmation before writing it (pass -y to skip the prompt):

# Generated by `minimal init`

[upstream] # Source of software & tooling
repo = "https://github.com/gominimal/pkgs"
branch = "main"
locked_commit = "9d36aa3d0fec09658fe3bbc676beeae49a89c53d"

[stack]
use = "rust"

[defaults]
state_key = "dev"

[session] # min session attach
packages = ["base", "vim"]
  • [upstream] pins the software supply chain: the package registry and the exact commit it is read from.
  • [stack] declares how the project builds. See the stack reference.
  • [defaults] sets build- and task-plane defaults, such as the state_key that tasks share persistent state under.
  • [session] is the one that matters for day-to-day work: it lists the tools every contributor’s session gets. See the minimal.toml reference for the full schema.

Declare your session’s tools

Edit the packages list under [session] to add whatever your team works with. Extend the existing list; do not add a second [session] table, since TOML does not allow a table to be defined twice.

[session] # min session attach
packages = ["base", "vim", "git", "gh", "ripgrep", "claude-code"]

Every name resolves against the Minimal Public Registry. Commit minimal.toml to your repository so every teammate, and every AI agent, gets an identical session.

Enter a session

Create and attach to an isolated session for the project:

min session activate --attach .

Minimal builds or fetches the declared packages, composes them into a sandbox seeded with a copy of your project (streamed in as a tarball), and drops you into a shell inside it. The [session] tools are on your PATH, and nothing touches the host. Type exit to leave; the session stays up, so you can min session attach back to it later.

Next: start a dev shell, or work alongside an agent.