Rules

Set custom instructions for Lunos.

You can provide custom instructions to Lunos by creating an AGENTS.md file. This is similar to Cursor’s rules. It contains instructions that will be included in the LLM’s context to customize its behavior for your specific project.

Initialize

To create a new AGENTS.md file, you can run the /init command in Lunos.

/init scans the important files in your repo, may ask a couple of targeted questions when the codebase cannot answer them, and then creates or updates AGENTS.md with concise project-specific guidance.

It focuses on the things future agent sessions are most likely to need:

build, lint, and test commands
command order and focused verification steps when they matter
architecture and repo structure that are not obvious from filenames alone
project-specific conventions, setup quirks, and operational gotchas
references to existing instruction sources like Cursor or Copilot rules

If you already have an AGENTS.md, /init will improve it in place instead of blindly replacing it.

Example

You can also just create this file manually. Here’s an example of some things you can put into an AGENTS.md file.

# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`

We are adding project-specific instructions here and this will be shared across your team.

Types

Lunos also supports reading the AGENTS.md file from multiple locations. And this serves different purposes.

Project

Place an AGENTS.md in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories.

Global

You can also have global rules in a ~/.config/opencode/AGENTS.md file. This gets applied across all Lunos sessions.

Since this isn’t committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow.

Claude Code Compatibility

For users migrating from Claude Code, Lunos supports Claude Code’s file conventions as fallbacks:

Project rules: CLAUDE.md in your project directory (used if no AGENTS.md exists)
Global rules: ~/.claude/CLAUDE.md (used if no ~/.config/opencode/AGENTS.md exists)
Skills: ~/.claude/skills/ — see Agent Skills for details

To disable Claude Code compatibility, set one of these environment variables:

export OPENCODE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills

Precedence

When Lunos starts, it looks for rule files in this order:

Local files by traversing up from the current directory (AGENTS.md, CLAUDE.md)
Global file at ~/.config/opencode/AGENTS.md
Claude Code file at ~/.claude/CLAUDE.md (unless disabled)

The first matching file wins in each category. For example, if you have both AGENTS.md and CLAUDE.md, only AGENTS.md is used. Similarly, ~/.config/opencode/AGENTS.md takes precedence over ~/.claude/CLAUDE.md.

Custom Instructions

You can specify custom instruction files in your opencode.json or the global ~/.config/opencode/opencode.json. This allows you and your team to reuse existing rules rather than having to duplicate them to AGENTS.md.

Example:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

You can also use remote URLs to load instructions from the web.

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}

Remote instructions are fetched with a 5 second timeout.

All instruction files are combined with your AGENTS.md files.

Keeping durable notes

To keep facts that should carry across sessions, such as “deploys go out on Tuesdays” or “the billing service owns the invoices table”, write them as small Markdown files and load them with instructions:

{
  "instructions": [".opencode/memory/*.md"]
}

Keep one fact per file, so each can be reviewed and deleted on its own.
Project notes live in the repo and are reviewed like any other change. Personal notes can live in ~/.config/opencode/memory/, loaded from your global config.
These files load alongside AGENTS.md and don’t compete with it.
Don’t put secrets in them: their contents are sent to your model provider as part of the prompt.

Long-term memory

Lunos can also keep a knowledge graph of what it learns, and recall the relevant parts in later sessions. It is off unless you turn it on:

{
  "memory": {
    "enabled": true,
    "scope": ["project"],
    "model": "small",
    "embedding": "local",
    "retrieval": { "max_tokens": 1500 },
    "limits": { "max_facts": 5000, "max_fact_chars": 2000 }
  }
}

What you need: uv and Python 3.10–3.13. Memory runs Cognee (Apache-2.0) in a local Python process. Lunos never installs Python for you: without it, memory stays off and says why.

Remembering. The agent saves facts with a memory_remember tool. You approve each one: the tool asks by default. It refuses:
- anything in a turn that used webfetch, websearch, an MCP resource, or read a file outside the project
- anything that looks like a key, token or password
Recalling. Relevant facts are added to your message in a <memory> block, each with where and when it was learned, capped at retrieval.max_tokens. The agent can also look things up with memory_search.
Your notes. Paragraphs in .opencode/memory/*.md are part of project memory, with no approval needed. When you edit or delete one, memory follows.
- The agent’s file edits in .opencode/memory/ ask first, and edits to the stored graph are refused by default. This stops the agent from writing memory through a file instead of the tool.
- Shell commands can still write files, so review changes to that folder like any other change.
Which model. memory.model picks the model that extracts facts and relationships: "small" (your small_model, the default), "inherit" (the main model) or "provider/model". It runs through your normal provider setup and data-residency policy. If the policy denies it, memory doesn’t start and the error names memory.model.
Embeddings are computed locally ("local"). The embedding model (about 87 MB) is downloaded once, from Hugging Face.
Where it’s stored.
- Project memory: .opencode/memory/graph/, which is never committed. Lunos writes a .gitignore there.
- "user" scope: in the Lunos data directory.
Reviewing it.
- In the TUI, /memory opens a browser: every fact with where it came from, the entities and relationships around the highlighted fact, and ctrl+d twice to forget it.
- lunos memory list, show <id> and search <query> show what is stored and where each fact came from.
- lunos memory export writes one Markdown file per fact for review in git.
- lunos memory forget <id> removes a fact. lunos memory purge --scope project --yes deletes the whole memory.
Turning it off:
- "memory": { "enabled": false }, or remove the key
- LUNOS_DISABLE_MEMORY=1, which overrides config
- /memory off for the current session
- "permission": { "memory": "deny" }, for all agents or one agent
When memory is off, no memory process starts, no memory files are created and the memory tools aren’t offered.

Referencing External Files

While Lunos doesn’t automatically parse file references in AGENTS.md, you can achieve similar functionality in two ways:

Using opencode.json

The recommended approach is to use the instructions field in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}

Manual Instructions in AGENTS.md

You can teach Lunos to read external files by providing explicit instructions in your AGENTS.md. Here’s a practical example:

# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

This approach allows you to:

Create modular, reusable rule files
Share rules across projects via symlinks or git submodules
Keep AGENTS.md concise while referencing detailed guidelines
Ensure Lunos loads files only when needed for the specific task