Import agent configuration

Overview

Your team probably keeps agent instructions in a code repository already: CLAUDE.md, AGENTS.md, Cursor rules, skills and more. When you link that repository, Oxagen reads those files on its default branch and shows you what each one would become. You pick what to import. Oxagen then opens one steering PR that links the repository and adds everything you picked.

Nothing steers an agent until you merge that PR. Oxagen never commits a file of its own to your code repository. After the steering PR merges, Oxagen can open a cleanup PR on the code repository that removes the text it imported. You review and merge that one yourself.

Where to start

The Import step has three doors. All three show the same step.

• Link a repository. On Repositories, choose Add Oxagen, pick a repository, and go to the Import step. For a repository that is not linked yet, the steering PR adds it to workspace.toml and imports your files. For a linked repository, the PR imports the files and leaves workspace.toml as it is. Choose Skip import to link the repository alone.
• Import on Steering. The Import button on the Steering page, and the same button in its empty state, reads the harness files of every repository the workspace already links.
• Review files on Repositories. When files on a linked repository's default branch have changed since the import, its row says so. Review files opens the Import step on that repository.

Only an organization Owner or Admin, or the workspace's Owner, can link a repository or open an import.

The Import step

You meet the step in three parts.

1. Pick. Oxagen lists every harness file it found, grouped by repository. Each row shows the file, what it becomes, and how many items it adds. A file that gives something to import starts ticked. Untick any file you do not want.
2. Review. Open a row to check its detail. For a Markdown file, that is each statement with its kind, force and load. For a skill, it is the files in its folder and its tool limit. For a settings file, it is the policies and the settings left out. For an MCP config, it is each server and what happens to its key. Oxagen shows duplicates of records you already have, and conflicts. A conflict needs your choice before the PR can open.
3. Open the steering PR. Choose Open steering PR. Oxagen reads each ticked file again on the default branch first. If a file changed since the scan, it refuses the import and asks you to scan again, so a PR never mixes old and new text.

Below the table, a meter shows how many tokens of always-on text the import adds against the always-on budget. A checkbox, ticked by default, offers the cleanup PR.

Files under fixtures/, test/, tests/, __tests__/, examples/ and node_modules/ start unticked and unread, with the reason shown. Tick one and Oxagen reads it.

A steering PR holds at most 299 files. A larger import splits. The first PR carries the link and the first files, and the rest open as their own PRs after it merges. A source file never splits across PRs.

Files Oxagen finds

Oxagen finds these files on the default branch. The oxagen repo scan command lists the same files.

A skill is the whole folder: its SKILL.md and every file beside it. A symlink imports nothing of its own. Oxagen lists it as skipped, names its target, and imports the target once under its own path.

What each file becomes

Every record from a repository is scoped to that repository. A file in a subfolder also applies only to that folder, such as apps/app/**.

Four rules sit behind the table.

• Skills stay whole. A skill, a command and a subagent file each keep their frontmatter and their procedure. Oxagen never splits one into statements. Source fields that a steering skill has no place for, such as model, are listed as not imported in the PR body.
• A Windsurf or Cline rule folder maps like Cursor rules. Each file in .windsurf/rules/ and .clinerules/ becomes one record. A Windsurf rule's trigger and globs map to load and scope the way a Cursor rule's do.
• A file with schema: steering-record/v1 frontmatter stays one record.
• Duplicates and conflicts. A statement that repeats a published record starts unticked. A statement that contradicts one needs your choice, to keep the record or replace it, before the steering PR opens.

Permissions, hooks and servers

Permissions become Cedar policies. In .claude/settings.json, each deny rule becomes a policy that forbids the action. Each ask rule becomes a policy that waits for a person's approval. An allow rule widens access, so it narrows nothing. Oxagen lists it as not imported. In .codex/config.toml, sandbox_mode = "read-only" forbids file writes, and approval_policy = "untrusted" makes every shell call wait for approval. The policies name Oxagen's built-in actions, such as builtin__shell, so each rule holds on every harness, not only the one that wrote it. A rule Cedar cannot hold, such as one on an MCP tool, stays in the file, and the step lists it with the reason.

Hooks are not imported. Oxagen lists every hook as not imported, with its reason, so you can see what stays behind.

MCP servers move with their keys in the vault. Each server becomes files under tools/servers/<name>/. Oxagen writes a key it finds in the config into the vault with a pending status when the steering PR opens. No run can use a pending key. It becomes active when the PR merges. A key never enters the steering repo. A server that runs on a laptop keeps its key there: Oxagen writes the variable name and tells you to add the key on each machine. A server starts unticked, with the reason shown, when it uses the older HTTP and SSE transport, when its URL holds a query string or a key, or when its key cannot be held in the vault.

What a run receives

Oxagen builds one bundle of steering for each workspace and repository. The host sends the repository the run works in, so a repository's records reach only runs in that repository. Records scoped to the whole workspace reach every run.

Each harness takes only so much text from the hook that starts a run, and Oxagen reads that limit from one table. A workspace can set an always-on budget below the limit, never above it. Set it as always_on_tokens under [steering] in the steering repo's steering/governance.toml.

Oxagen fills that room with the most relevant records first. It ranks by force, with must before should, then puts records scoped to the run's repository ahead of workspace records, then takes the newest first. It skips a record that does not fit and keeps going, so one long record near the top does not push out every short one beneath it. The run record names every record it cut and why.

This is why the cleanup PR retires CLAUDE.md. A single file cannot be relevant to every task, and it sits in the repository beside the records made from it, so the two drift apart. Records let each run get the few rules that fit its repository and its harness, up to what that harness can take.

The cleanup PR

The Import step offers a cleanup PR, ticked by default. When the steering PR merges, Oxagen opens a pull request on the code repository titled "Remove agent configuration imported into the steering repository". It never pushes to the default branch.

• A skill goes with the other files in its folder. A command, a subagent file and a rule go whole.
• An instruction file loses only the statements Oxagen imported. A file left empty is deleted. Lines you chose not to import stay.
• Settings files and MCP configs stay, because other tools read them.
• A file that changed after the import stays, and the Repositories page marks it for review.

The cleanup PR says what you lose. Agents that Oxagen does not wrap stop reading the removed text, because it now lives only in the steering repo.

Later changes

A push to the default branch that touches a harness file rescans it. The Repositories row for that repository then shows how many files changed since the import, and Review files opens the Import step on them. Oxagen compares each file's hash with the one it imported, and a file you skipped stays skipped.

Personal files

CLAUDE.local.md, ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md are personal. They become your own memories, not records, and they steer nothing until a person promotes a memory into a steering record.

• The Import step lists a repository's CLAUDE.local.md as a personal file. If you leave it ticked, Oxagen stores its statements as waiting memories. They wait on the Memories tab.
• Only the CLI reads the two files in your home folder. Run oxagen steering import --harness claude-code for ~/.claude/CLAUDE.md, or --harness codex for ~/.codex/AGENTS.md.

The same flag reads your own skills, commands and subagent files from ~/.claude, ~/.agents/skills and ~/.cursor. Those become records for the whole workspace, because a folder on your laptop belongs to no repository. A bare call previews the rows and writes nothing. Add --yes to open the steering PR and store the memories. See oxagen steering import for every flag.

The Skills tab

Steering has a Skills tab beside Records and Memories. It lists every skill with its source, its repository, and its tool limit. The source reads Imported skill, Imported command, Imported subagent, Proposed, From a run, or Written here.

A tool limit is a Cedar policy on the skill. A subagent file's tools list becomes that policy, and it is the one source. When Oxagen delivers the skill, it renders the policy into the skill's allowed-tools, where the harness can read it. The tab shows one cell per harness for each skill that has a limit.

The limit holds only where the harness says which skill made a tool call. Today that is Claude Code, and only for a skill that runs as a subagent. A skill that runs inline in Claude Code reads Harness. Codex, Cursor and stella read Falls back, because none of them names the skill behind a call and none has Oxagen's allowed-tools field. The skill still works there, and it gets the main agent's rules.