Skip to main content

Migrate Hand-Edited Tool Configs

This guide walks through bringing an existing hand-edited ~/.claude/settings.json or ~/.codex/config.toml into drwn's managed model without losing your existing MCP servers or custom skills.

Inspect What You Already Have​

drwn scan is the planned non-mutating discovery surface for exactly this problem. It is currently a placeholder: the command runs and is intended to report local agent tool config it finds and suggest machine inventory, explicit machine selection, and project-config candidates. Until the implementation lands, inventory manually:

cat ~/.claude/settings.json
cat ~/.codex/config.toml

Record every MCP server entry, every custom skill directory, and every hand-edited target setting.

Register Existing MCP Servers​

For each MCP server in your hand-edited config, write a small JSON definition and add it to the standalone inventory:

drwn machine mcp add ./github-mcp.json --as github
drwn machine mcp list

If the server should be selected for machine-scope sessions, enable it in explicit machine intent:

drwn machine mcp enable github

If the server only applies to one project, scope it there instead:

cd /path/to/project
drwn init
drwn add mcp github

Migrate Custom Skills​

Inventory any custom skill directories the agent tools were already reading from. For each one:

drwn machine skill install <npm-package-or-local-path>
drwn machine skill install <local-path>
drwn machine skill list

If the skill should be available globally:

drwn machine skill enable <skill-name>
drwn write --scope machine --skills-only --dry-run

If the skill should apply only to one project, scope it through the project config instead of selecting it for machine scope.

Preview The Managed Write​

drwn write --dry-run

Compare the planned changes against your hand-edited files. drwn will:

  • preserve user-owned entries it did not write
  • replace its own managed sections in the generated MCP config and managed symlinks
  • warn when a hand-edited entry conflicts with a managed one

Iterate​

Repeat machine skill|mcp inventory operations, machine enable commands, project add commands, and write --dry-run until the dry run matches what you want. Then run:

drwn write

Conservative Cleanup Model​

drwn does not delete hand-edited entries it did not create. When a managed write would otherwise replace a user-owned entry, drwn preserves the user-owned version and reports the ownership conflict instead of overwriting. This is by design: migration should never silently destroy something you hand-wrote.

Use drwn doctor after migration to surface remaining ownership conflicts, stale links, and unresolved references.

See Also​