# Bring your Claude Code setup

[← One Code user guide](README.md)

One Code reads the same configuration files as Claude Code, so your
existing setup works without changes. There's no import step and nothing
to convert. Open a project that already has a `.claude/` directory, and One
Code picks up each of the following as it is.

That's the default, Claude-compatible mode. If you'd rather One Code ignore
your Claude Code setup entirely, switch to independent mode. See
[Run One Code on its own setup](#run-one-code-on-its-own-setup).

## Project instructions: CLAUDE.md

One Code loads `CLAUDE.md` files and includes them in the model's context
exactly as Claude Code does: your global `~/.claude/CLAUDE.md`, then the
`CLAUDE.md` in every directory from the filesystem root down to the working
directory, plus any `CLAUDE.local.md` beside them for private instructions.
`@path` imports are expanded in place.

If the project has no `CLAUDE.md` or `CLAUDE.local.md` anywhere on that
path, One Code loads its `AGENTS.md` files instead, in the same places, plus
any `.claude/AGENTS.md`. So a repository that standardized on `AGENTS.md`
works too. Once a `CLAUDE.md` exists, the `AGENTS.md` files are left out,
the same rule Claude Code follows.

Claude Code's `instructionFiles` option changes that rule, and One Code
honours it: `claude-md` never loads `AGENTS.md`, `claude-md-and-agents-md`
loads it beside `CLAUDE.md`, and `managed-only` drops your own and the
project's instruction files.

To give One Code instructions that Claude Code shouldn't read, add an
`ONECODE.md`. See [ONECODE.md](sessions-and-context.md#onecodemd).

To generate a `CLAUDE.md` for a project that lacks one, run `/init`. It sends
the prompt Claude Code's `/init` sends: the model reads the project and writes
down how to build, lint, and test it and the big-picture architecture, folding
in your README and any Cursor, Copilot, or `AGENTS.md` rules. If the project
already has a `CLAUDE.md`, it suggests improvements instead.

## Skills, commands, and agents

| Directory | Becomes |
|---|---|
| `.claude/skills/`, `~/.claude/skills/`, `~/.agents/skills/` | Skills the model can call and you can run as `/<name>`. `/skills` manages them. |
| `.claude/commands/`, `~/.claude/commands/` | Slash commands with the same names, with `$ARGUMENTS` substitution. |
| `.claude/agents/`, `~/.claude/agents/` | Subagent definitions with their model, tools, and instructions. `/agents` lists them. |
| `.claude/workflows/`, `~/.claude/workflows/` | Saved `ultracode` workflow scripts. |

See [Skills, plugins, and MCP](skills-plugins-and-mcp.md) and
[Subagents and workflows](subagents-and-workflows.md).

## Plugins

Plugins installed under `~/.claude/plugins` are picked up, with their
agents, skills, commands, hooks, MCP servers, and language-server
configuration, each namespaced by plugin. The `enabledPlugins` key in your
settings files is honored. `/plugins` browses and installs more; anything
One Code installs goes to its own plugin directory. See
[Plugins](skills-plugins-and-mcp.md#plugins).

## MCP servers

Servers in `.mcp.json`, in `~/.claude.json`, and in
`.claude/settings.local.json` are connected at startup, after a one-time
approval for project servers. Only the `mcpServers` key of `~/.claude.json`
is read; the rest of that file is left alone. See
[MCP servers](skills-plugins-and-mcp.md#mcp-servers).

## Settings files

One Code reads these Claude Code files and never writes them:

| File | Scope |
|---|---|
| `~/.claude/settings.json` | User |
| `.claude/settings.json` | Project |
| `.claude/settings.local.json` | Project, local |
| Managed settings (`/Library/Application Support/ClaudeCode/managed-settings.json` on macOS, the Linux equivalent elsewhere) | Organization |
| `~/.claude.json` | User, `mcpServers` only |

`CLAUDE_CONFIG_DIR` relocates the user-scope files, as it does in Claude
Code.

The keys One Code honors:

| Key | Scopes | Notes |
|---|---|---|
| `permissions.allow`, `permissions.deny`, `permissions.ask` | All | Project allow rules need one-time approval. See [Permissions](permissions-modes-and-auto-mode.md#permission-rules). |
| `permissions.defaultMode` | All | A project file can't select `auto` or `bypassPermissions`. |
| `permissions.disableBypassPermissionsMode` | All | `"disable"` refuses bypass mode from any source. |
| `permissions.blockReadsOutsideWorkingDirectories` | All | `true` makes the read tools refuse paths outside the working directories. See [Reads outside the working directories](permissions-modes-and-auto-mode.md#reads-outside-the-working-directories). |
| `permissions.additionalDirectories` | All | Project directories need one-time approval. See [Workspace directories](permissions-modes-and-auto-mode.md#workspace-directories). |
| `autoMode.*` | User, managed | Never read from project files. See [Configure auto mode](permissions-modes-and-auto-mode.md#configure-auto-mode). |
| `hooks` | All | Project hooks need one-time approval. See [Hooks](hooks.md). |
| `env.CLAUDE_CODE_SUBAGENT_MODEL` | User, managed | The only `env` key read. |
| `enabledPlugins` | All | Later scope wins per plugin. |
| `enabledMcpjsonServers`, `enableAllProjectMcpServers` | User | Never from a project file, local included. |
| `disabledMcpjsonServers` | User, local | |
| `mcpServers` | `~/.claude.json`, `.claude/settings.local.json` | |

Not honored: other `env` keys,
`includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
`cleanupPeriodDays`, and `spinnerTipsEnabled`. Run `/doctor report` to see,
for every file found, which keys were used, ignored, or refused.

## Permission rules

The `allow`, `deny`, and `ask` rules in your settings drive the permission
gate, with `deny` always winning. Claude Code's PascalCase tool names
(`Read`, `Bash`, `Edit`, `Task`, `WebFetch`, and the rest) are accepted
verbatim and mapped to the matching tool. See
[Permissions, modes, and auto mode](permissions-modes-and-auto-mode.md).

## Hooks

Claude Code command hooks run unchanged, with the same standard-input JSON,
exit-code meaning, and output format. Eight events are supported. A
project's hooks run only after you approve them once. See [Hooks](hooks.md).

## Memory

One Code keeps per-repository memory in Claude Code's own folder,
`~/.claude/projects/<slug>/memory/`, so both tools read and write the same
memories. This is the one place One Code writes under `~/.claude`. Run
`/memory` to open memory and instruction files. See
[Memory](sessions-and-context.md#memory).

## Run One Code on its own setup

Maybe you don't use Claude Code at all, or you want One Code's
instructions, agents and memory kept apart from it. Independent mode does
that: One Code stops reading anything of Claude Code's. No `~/.claude`, no
project `.claude/`, no `CLAUDE.md`, no `~/.claude.json` or `.mcp.json`, and
no managed settings either.

To switch, run `/memory`, press **↑** to reach the **Config sources** row,
and press **Enter**. One Code asks first, since this changes everywhere it
reads configuration from: press **Enter** again to switch, or **Esc** to
keep the mode you have. The row shows **(from next start)** until you restart
One Code, because the switch applies to the next session, not the one
you're in. `/doctor` shows which mode is running.

Here's where each mode looks:

| What | Claude-compatible (default) | Independent |
|---|---|---|
| Instructions | `CLAUDE.md` family, or `AGENTS.md` when there's none; `ONECODE.md` | `AGENTS.md` in every directory; `ONECODE.md` |
| Skills | `.claude/skills/`, `~/.claude/skills/`, `.agents/skills/`, `~/.agents/skills/`, pi's skills | `.agents/skills/`, `~/.agents/skills/`, pi's skills |
| Commands, agents, workflows | `.claude/` and `~/.claude/` | `.onecode/` and `~/.onecode/` (`commands/`, `agents/`, `workflows/`) |
| Settings, hooks, permissions | Claude Code's settings files, managed settings, and One Code's files | One Code's files only: `~/.onecode/settings.json` and the per-repository one |
| MCP servers | `~/.claude.json`, `.mcp.json`, `.claude/settings.local.json`, pi's `mcp.json` files | pi's `mcp.json` files |
| Memory | `~/.claude/projects/<slug>/memory/` | `~/.onecode/projects/<slug>/memory/` |
| Worktrees | `.claude/worktrees/` | `.onecode/worktrees/` |

In independent mode, the settings you'd put in `~/.claude/settings.json`
(permissions, `defaultMode`, hooks, the `env` block, `autoMode`) go in
`~/.onecode/settings.json` instead, with the same keys. Memories don't move
between modes, so each mode starts with its own.

Independent mode skips managed settings too. If your organization manages
Claude Code with a policy file, that policy doesn't apply to One Code in
this mode.

## What stays separate

One Code's own state lives in `~/.onecode`. Everything it saves (a chosen
subagent model, auto-mode options, rules added with `/allow`, disabled MCP
servers, project approvals, plan files, OAuth tokens) goes there or to a
per-repository file under it, never into your Claude Code configuration.
See [Where settings live](configuration.md#where-settings-live).

## What does not carry over

Features that need Claude Code's own hosted or desktop services aren't
available. For the full list of tools, commands, and skills that are
missing or different, see
[Differences from Claude Code](differences-from-claude-code.md).