# Initialize a project

> Set up a project with min init, declare your session's tools in minimal.toml, then enter an isolated session with min session activate.

Source: https://minimal.dev/docs/start/2-setup
Last updated: 2026-08-25

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:

```shell
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):

```toml
# Generated by `min 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](https://minimal.dev/docs/reference/stack-specs).
- `[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](https://minimal.dev/docs/reference/minimal-dot-toml) 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.

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

Every name resolves against the [Minimal Public Registry](https://github.com/gominimal/pkgs). 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:

```shell
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](https://minimal.dev/docs/start/4-dev-shell), or [work alongside an agent](https://minimal.dev/docs/start/5-agents).