Configuration

Configuration Hierarchy

Settings are merged from multiple sources, with later sources overriding earlier ones (bottom wins):

Project Guidance: OPENANALYST.md

Create an OPENANALYST.md file in your project root to provide AI instructions and project context. This file is auto-detected at startup and injected into the system prompt.

# Project: My App

## Architecture
This is a React + Node.js monorepo with:
- /frontend — React SPA (Vite)
- /backend — Express API server
- /shared — Shared types and utilities

## Guidelines
- Use TypeScript strict mode
- Prefer functional components with hooks
- All API routes must have error handling middleware
- Tests use Vitest for frontend, Jest for backend

## Common Tasks
- Run dev: `npm run dev` (starts both frontend and backend)
- Run tests: `npm test`
- Deploy: `npm run deploy` (requires AWS credentials)

Settings File

The main settings file supports these sections:

{
  "model": "openanalyst-beta",
  "permission_mode": "workspace-write",
  "autoMode": "auto-edit",
  "extendedThinking": { "enabled": true, "budgetTokens": 10000 },
  "env": {
    "OPENANALYST_API_KEY": "sk-oa-..."
  },
  "permissions": {
    "allow": ["bash(npm test)", "write_file(src/**)"],
    "deny": ["bash(rm -rf *)"]
  },
  "hooks": {
    "PreToolUse": [{ "command": "echo $TOOL_NAME" }],
    "PostToolUse": [{ "command": "echo done" }],
    "SessionStart": [],
    "SessionEnd": [],
    "SubagentSpawned": [],
    "ModelSwitch": []
  },
  "subagents": {
    "explore": { "model": null, "maxTurns": 10 },
    "plan": { "model": null, "maxTurns": 5 }
  },
  "modelAliases": {
    "fast": "openanalyst-beta",
    "smart": "claude-sonnet-4-6"
  },
  "mcp": {
    "servers": {
      "my-server": {
        "transport": "stdio",
        "command": "node",
        "args": ["server.js"]
      }
    }
  },
  "sandbox": {
    "filesystem_mode": "workspace",
    "allowed_mounts": ["/data"]
  }
}

Permission Modes

Set via CLI flag, config, or slash command:

# CLI flag
openanalyst --permission-mode workspace-write

# In settings.json
{ "permission_mode": "workspace-write" }

# During a session
/permissions workspace-write

Hooks

Hooks are shell commands that execute in response to lifecycle events:

Environment Variables

Authentication

Runtime

File Structure

Project-Level (created via /init)

project/
├── OPENANALYST.md                    # Project-specific AI instructions
├── OPENANALYST.local.md              # Personal project instructions (gitignored)
├── .openanalyst.json                 # Shared project defaults
├── .openanalyst/
│   ├── settings.json                 # Project-level settings
│   ├── settings.local.json           # Machine-local overrides (gitignored)
│   ├── .env                          # Provider API keys (gitignored)
│   ├── .mcp.json                     # MCP server configuration
│   ├── sessions/                     # Saved conversation sessions
│   ├── skills/                       # Multi-file SKILL.md definitions
│   ├── commands/                     # Simple slash commands
│   ├── rules/                        # Path-specific instruction files
│   ├── agents/                       # Custom subagent definitions
│   ├── hooks/                        # Reusable hook scripts
│   └── output-styles/                # Custom output formatting

User-Level (all projects)

~/.openanalyst/
├── settings.json                     # User-wide settings
├── .env                              # Global API keys
├── credentials.json                  # Saved provider credentials
├── skills/                           # User skills (available everywhere)
├── commands/                         # User slash commands
├── rules/                            # User rules
├── agents/                           # User agents
└── output-styles/                    # User output styles

3-Level Config Hierarchy

All configuration (rules, skills, agents, output-styles) loads from three levels, with later levels overriding earlier ones: