Skip to content

Getting started

Prerequisites

Section titled “Prerequisites”

You need Node.js 22.5 or later and OpenCode. Open a terminal in the project directory where you want to keep your harness configuration.

Initialize your project

Section titled “Initialize your project”

Create the configuration and run the first build:

Terminal window
npx atlante init

By default, init also registers the read-only Atlante MCP server in the OpenCode configuration for this project. It selects the first existing file in this order: .opencode/opencode.jsonc, .opencode/opencode.json, opencode.jsonc, and opencode.json; when none exists, it creates root opencode.jsonc. Use npx atlante init --no-mcp when you want to skip that registration. See the MCP reference for the server contract.

OpenCode is the default materialization target. The --hosts option additionally supports Claude Code, with its own native output directories and MCP registration; the CLI reference documents the host selection.

Inspect the configuration and output

Section titled “Inspect the configuration and output”

Open atlante.jsonc. Its configuration selects the preset through extends:

atlante.jsonc
{
  "$schema": "https://atlante.sh/schema/v0.1/schema.json",


  // Extend the first-party package preset. You can override any value or agent
  // below; your local configuration takes precedence over the inherited one.
  "extends": "@atlante/pack",
}

After init completes its first build, the project contains source configuration, host configuration, generated native output, and Atlante state:

The selected host configuration is either .opencode/opencode.jsonc, .opencode/opencode.json, opencode.jsonc, or opencode.json, depending on which file already exists.

my-project/
├── atlante.jsonc
├── .opencode/
│   ├── opencode.jsonc             # selected host config when nested (or .json)
│   ├── agents/
│   │   └── atlante.md
│   └── skills/
│       └── atlante/
│           ├── brainstorm/SKILL.md
│           ├── plan/SKILL.md
│           ├── build/SKILL.md
│           ├── review/SKILL.md
│           └── harness/SKILL.md
├── opencode.jsonc                 # selected host config when root-level (or .json)
└── .atlante/
    └── opencode-native.json

The files have different roles:

  • atlante.jsonc is the source configuration. Keep it and any resources you author in version control.
  • opencode.jsonc is the default host configuration created by init when no OpenCode configuration exists. If an OpenCode configuration already exists, init updates the first file in its precedence order; the Atlante MCP entry for the detected host dialect is managed there alongside host settings.
  • .opencode/agents/atlante.md and the skill files under .opencode/skills/atlante/ are native output. Open the agent file to inspect what the build produced, but make changes in the source configuration or its resources.
  • .atlante/opencode-native.json is the ownership manifest. It tells later builds which native files Atlante may update or remove without claiming unrelated OpenCode files.

init adds .atlante/, .opencode/skills/atlante/, and the exact .opencode/agents/atlante.md entry to .gitignore. These entries cover default generated native files and Atlante state; the authored configuration remains the versioned source. The OpenCode configuration is host configuration rather than generated native output.

See Materialization for output ownership and Troubleshooting when generated output must be versioned or recovered after an edit.

Open the harness in OpenCode

Section titled “Open the harness in OpenCode”

Start OpenCode from the project root, where init created .opencode/, or restart an existing session so it discovers the new files. The atlante agent should now be available.

You can also inspect the agent list from the terminal:

Terminal window
opencode agent list

Look for atlante in the list. If it is missing, confirm that the project root contains .opencode/agents/atlante.md, then restart OpenCode. Choose a model and configure permissions through OpenCode’s configuration. These settings remain in OpenCode’s own files when Atlante rebuilds the harness.

You now have the default harness built from a configuration in your project.

Use a project-local CLI

Section titled “Use a project-local CLI”

For ongoing work, install the CLI as a development dependency in the project that owns your package.json:

Terminal window
npm install --save-dev atlante

If the repository has no package.json, create one with your package manager before installing. Commit the manifest and lockfile with your configuration so other contributors can install the same CLI version.

After installing locally, run the project-local CLI rather than requesting @latest. For example, rebuild after a configuration change with:

Terminal window
npx atlante build

Installing the CLI does not require another initialization. For normal changes, edit the configuration and run build.

Next steps

Section titled “Next steps”