How I Use ~/Agents as a Safe Workspace for Claude Code and Codex

intoffset — Wed, 22 Apr 2026 19:09:19 +0000

The problem

The more I used Claude Code and Codex, the more I realized I needed a clearer boundary between real projects, temporary clones, and experiments.

Sometimes the problem was not the agent. It was my filesystem.

I was asking agents to work across real projects, temporary clones, half-finished playgrounds, and writing notes without giving them a clear place to start.

That made every task slightly more fragile.

Was this repository safe to edit? Was that clone only for reference? Should the agent create a reproduction inside the product repo, or somewhere else? Was this note supposed to be committed?

So I created a dedicated workspace: ~/Agents.

It is not a framework or a tool. It is a filesystem boundary that tells both me and the agent what is safe to touch, what is reference-only, and where experiments should go.

This article describes the layout I use for that workspace.

Why create a dedicated workspace?

Agent-assisted development often does not fit neatly inside a single project.

In a normal week, you may ask an agent to:

compare multiple Git repositories
clone an external project and inspect its implementation
build a small playground to test a library
keep research notes while writing an article
prototype something without touching a production repository

Putting all of that inside ~/src or ~/work can get messy fast.

The problem is not only visual clutter. The bigger issue is losing track of what is safe to touch.

Is this directory a long-lived project? Is it a temporary clone? Can an agent edit it? Is it reference-only? Is this file supposed to be committed, or is it just scratch work?

Humans can often infer that from memory. Agents need more explicit boundaries.

That is why I keep agent-related work under ~/Agents. It gives me a simple way to say:

This is the workspace. These are the projects. This one is read-only. Put the experiment over there. Write the notes here.

What belongs in `~/Agents`?

In my setup, ~/Agents has four main responsibilities:

group multiple independent Git repositories
host playgrounds and experiments
keep external clones and investigation notes nearby
define a clear working area for AI agents

The important point is that ~/Agents itself is not a giant monorepo.

It is closer to a workspace root. The projects inside it remain independent. The root only contains shared policies and configuration that help agents operate consistently.

That distinction matters. A monorepo implies shared ownership, shared tooling, and shared change management. This workspace is different: it groups related working contexts without pretending they are one software project.

Basic root layout

A minimal root layout looks like this:

~/Agents/
|-- AGENTS.md
|-- CLAUDE.md
|-- .gitignore
|-- .mcp.json
|-- .agents/
|   `-- skills/
|-- .claude/
|   |-- settings.json
|   |-- settings.local.json
|   `-- skills/
|-- .codex/
|   `-- config.toml
`-- ...

The names of your actual work repositories do not matter as much as the role of the root files.

AGENTS.md: workspace-level operating rules for AI agents
CLAUDE.md: Claude Code compatibility entry point, usually a symlink to AGENTS.md
.gitignore: a whitelist-style ignore file for the root repository
.mcp.json: MCP server configuration for Claude Code
.agents/skills/: the canonical location for shared skills
.claude/settings.json: Claude Code permissions and allowed commands
.claude/settings.local.json: machine-specific Claude Code settings, not committed
.claude/skills: Claude Code skill path, usually a symlink
.codex/config.toml: Codex configuration

This root is mostly about coordination. Actual implementation work belongs in the projects under it.

Keep projects as independent repositories

The root of ~/Agents is for shared configuration. Projects, prototypes, external clones, and writing work live under it as separate directories.

For example:

~/Agents/
|-- AGENTS.md
|-- CLAUDE.md
|-- .gitignore
|-- .mcp.json
|-- .agents/
|-- .claude/
|-- .codex/
|-- product-app/          # Long-lived product work
|-- playground-sdk/       # SDK or library experiments
|-- playground-browser/   # Browser automation experiments
|-- fork-library/         # External repository investigation
|-- docs-writing/         # Articles and documentation drafts
`-- research-notes/       # Notes from investigation work

The naming convention does not need to be strict. The useful part is separating different kinds of work instead of pushing everything into one vague directory.

With this structure, you can give an agent instructions like:

Treat fork-library as reference-only.
Create the smallest reproduction in playground-sdk.
Write the investigation notes in docs-writing.

That instruction is much easier to follow when the filesystem already reflects the distinction.

It also prevents experimental code from leaking into an existing project just because that project happened to be the current working directory.

Put workspace policy in `AGENTS.md`

At the root, I prefer to start with workspace policy before tool-specific configuration.

AGENTS.md should explain things like:

this directory contains multiple independent projects
each subdirectory should be treated as its own working unit
some directories may be reference-only
exploratory reading is generally allowed
edits should stay within the project or directory named in the task

For example, a minimal root AGENTS.md might look like this:

# Workspace rules

This directory contains multiple independent projects. Each subdirectory is a self-contained project.

- Treat each subdirectory as its own working unit.
- Do not edit external clones unless explicitly asked.
- Put experiments in `playground-*` directories.
- Keep project-specific commands inside each project.

This file is not where I put detailed build commands for every project. Those belong inside each project.

The root AGENTS.md is more like the constitution of the workspace. It tells the agent how to think about the directory tree before it starts editing files.

This follows the same idea as the AGENTS.md convention: give coding agents a predictable, dedicated place to find project-specific instructions. README files are for humans; AGENTS.md is where I put the extra operating context an agent needs before it starts editing files.

Use a whitelist-style `.gitignore`

Because ~/Agents contains many repositories and temporary directories, tracking everything from the root repository would be a mistake.

I prefer the opposite approach: ignore everything by default, then explicitly allow only the shared root configuration.

For example:

# Ignore everything by default
*

# Root-level workspace policy
!.gitignore
!AGENTS.md
!CLAUDE.md
!.mcp.json
!skills-lock.json

# Agent settings
!.claude/
!.claude/settings.json
!.claude/skills
!.codex/
!.codex/config.toml

# Shared skills
!.agents/
!.agents/skills/
!.agents/skills/**

With this setup, you can add more clones, playgrounds, and scratch directories without accidentally committing them from the root repository.

The root repository only tracks the files that define how the workspace is operated.

Using Claude Code and Codex together

I use both Claude Code and Codex, so I try to keep the conceptual model shared even when the actual configuration files differ.

Put shared rules in `AGENTS.md`

For Claude Code compatibility, CLAUDE.md can be a symbolic link to AGENTS.md:

CLAUDE.md -> AGENTS.md

Codex can use .codex/config.toml, while Claude Code can use .claude/settings.json.

Those files are tool-specific. The workspace rules are not. Keeping the shared rules in AGENTS.md avoids maintaining two separate explanations of the same workspace.

Make `.agents/skills/` the canonical skills directory

For shared skills, I use .agents/skills/ as the canonical location.

For example:

npx skills add <github-url> --skill <skill-name> --agent codex -y

If Claude Code should see the same skills, .claude/skills can point to the shared directory:

.claude/skills -> ../.agents/skills

This avoids maintaining separate copies for different agents.

Let MCP configuration differ by tool

MCP configuration is one place where the files naturally differ by tool.

Claude Code may read .mcp.json. Codex may read .codex/config.toml.

I do not try to force those into one file. Instead, I keep the policy in AGENTS.md:

The same MCP capabilities should be available from both agents where practical.

Then each tool gets the configuration format it expects.

Operational benefits

The practical benefit is simple: when I start a new agent-assisted task, I already know where it belongs.

New project? Put it under ~/Agents.

External repository investigation? Clone it under ~/Agents.

Article research? Keep the notes near the experiments.

The workspace keeps related things close together while still preserving repository boundaries.

It also makes task prompts shorter and more precise because the directory layout carries some of the meaning.

Instead of explaining every time that an external clone is reference-only, you can make that convention part of the workspace policy.

The main benefits are:

fewer accidental edits to real projects
a predictable place for experiments and reproductions
easier prompts because the workspace already encodes intent
cleaner separation between durable projects and temporary investigation work

Things to be careful about

~/Agents should not become a dumping ground for everything.

I try to keep a few rules:

separate long-lived projects, playgrounds, external clones, and notes
be careful with .env files, credentials, and private notes
keep workspace-level rules separate from project-level rules
do not turn the root into a monorepo unless that is actually the goal

The root AGENTS.md should describe the workspace. Build commands, test commands, and project-specific constraints should live in the relevant project.

That separation matters because agents follow local context. If every rule lives at the root, the root file becomes noisy and less useful.

Conclusion

~/Agents is less about creating a special directory for AI and more about creating a clear boundary for agent-assisted work.

For me, it serves three purposes:

work across multiple Git repositories
create new playgrounds quickly
keep lightweight investigations for Claude Code and Codex in one shared context

You do not need to build the whole structure at once.

A good starting point is:

create ~/Agents
add AGENTS.md
add a whitelist-style .gitignore
create a playground-* directory for experiments

Claude Code settings, Codex settings, skills, and MCP configuration can be added later when they become useful.

The main value is the boundary. Once the workspace has a clear shape, it becomes much easier to tell an AI agent where to read, where to write, and what not to touch.

DEV Community: intoffset

How I Use ~/Agents as a Safe Workspace for Claude Code and Codex

The problem

Why create a dedicated workspace?

What belongs in ~/Agents?

Basic root layout

Keep projects as independent repositories

Put workspace policy in AGENTS.md

Use a whitelist-style .gitignore

Using Claude Code and Codex together

Put shared rules in AGENTS.md

Make .agents/skills/ the canonical skills directory

Let MCP configuration differ by tool

Operational benefits

Things to be careful about

Conclusion

What belongs in `~/Agents`?

Put workspace policy in `AGENTS.md`

Use a whitelist-style `.gitignore`

Put shared rules in `AGENTS.md`

Make `.agents/skills/` the canonical skills directory