#AGENTS.md & Project Init

OpenCode generates AGENTS.md via /init, following the AGENTS.md open standard shared with Codex, Cursor, and others.

#What /init Does

In the TUI:

/init

OpenCode will:

1. Scan project structure (language, package manager, test commands, etc.)
2. Create AGENTS.md at the repo root
3. Write a summary of build/test/layout conventions

Tip: Review after generation—remove wrong guesses and add team-specific rules.

#What to Put in AGENTS.md

Recommended:

• One-line project description
• Install commands (npm install / pnpm i / uv sync)
• Test, lint, typecheck commands
• Directory layout (src/, packages/)
• PR / commit conventions
• Don’ts (no .env commits, no force push to main)

Example:

# AGENTS.md

## Project
Monorepo: frontend `apps/web`, API `packages/api`.

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Conventions
- API changes must update OpenAPI docs
- Do not change lockfiles unless dependencies actually change

#@ File References

In the TUI, use @path for precise context:

@src/auth/login.ts explain the login flow

More token-efficient than blind globbing. Works for files and directories.

#AGENTS.md vs opencode.json

AGENTS.md is for human-readable conventions; opencode.json is for machine-enforced policy (permission, model).

#Feedback Loop

When the agent repeats mistakes:

1. Correct in chat
2. Ask to update AGENTS.md: “Add this rule to AGENTS.md”
3. Merge via code review

Combine with pre-commit and CI to harden soft rules.

#Monorepos

OpenCode loads context from the Git root downward. For complex monorepos, use sections in the root AGENTS.md per package rather than many nested files (OpenCode primarily uses root /init output).

#Verify

After init, in Plan mode ask:

According to AGENTS.md, what is our test command?

A correct answer means context loaded successfully.

#Next Steps

• Agents & Permissions
• Architecture & Runtime