Data locations

Where Deep Agents Code stores configuration, sessions, and customization files

Deep Agents Code stores data in two directory hierarchies:

• ~/.deepagents/ — Deep Agents-specific data (agent memory, skills, sessions)
• ~/.agents/ — Tool-agnostic data (skills shared across AI CLI tools)

Directory structure

~/.deepagents/
├── .state/                  # Per-machine Deep Agents Code state (managed automatically)
│   ├── sessions.db          #   SQLite database for conversation checkpoints
│   ├── history.jsonl        #   Command input history
│   ├── chatgpt-auth.json    #   ChatGPT OAuth token for the openai_codex provider
│   ├── ...                  #   Other markers & credentials
└── {agent}/                 # Per-agent directory (default: "agent")
    ├── AGENTS.md            # User customizations to agent instructions
    ├── skills/              # User-level skills
    │   └── {skill-name}/
    │       └── SKILL.md
    └── agents/              # Custom subagent definitions
        └── {subagent-name}/
            └── AGENTS.md

~/.agents/                   # Tool-agnostic alias (shared across AI CLIs)
└── skills/                  # Skills available to any compatible tool
    └── {skill-name}/
        └── SKILL.md

{project}/                   # Project-level (in git repo root)
├── AGENTS.md                # Project instructions (root-level)
└── .deepagents/
│   ├── AGENTS.md            # Project instructions (preferred location)
│   ├── skills/              # Project-specific skills
│   │   └── {skill-name}/
│   │       └── SKILL.md
│   └── agents/              # Project-specific subagents
│       └── {subagent-name}/
│           └── AGENTS.md
└── .agents/                 # Tool-agnostic project skills
    └── skills/
        └── {skill-name}/
            └── SKILL.md

What goes where

Data	Location	Read/Write	Notes
Sessions	~/.deepagents/.state/sessions.db	R/W	SQLite checkpoint database
Input history	~/.deepagents/.state/history.jsonl	R/W	JSON-lines, up/down arrow recall
ChatGPT OAuth token	~/.deepagents/.state/chatgpt-auth.json	R/W	Backs the openai_codex provider; created when you sign in with ChatGPT and refreshed automatically. Readable only by your user account.
Base instructions	Package default_agent_prompt.md	R	Immutable, updated with Deep Agents Code upgrades
User customizations	~/.deepagents/{agent}/AGENTS.md	R/W	Appended to base instructions
Project instructions	.deepagents/AGENTS.md or AGENTS.md	R	Both loaded if present
User skills	~/.deepagents/{agent}/skills/	R/W	Agent-specific skills
Shared skills	~/.agents/skills/	R	Tool-agnostic, cross-CLI
Project skills	.deepagents/skills/ or .agents/skills/	R	Project-scoped
Custom subagents	~/.deepagents/{agent}/agents/	R/W	User-defined subagents
Project subagents	.deepagents/agents/	R	Project-defined subagents

Precedence rules

When the same item exists in multiple locations, higher precedence wins completely (no merging).

Skills

Precedence order (lowest to highest):

1. ~/.deepagents/{agent}/skills/ — User Deep Agents Code
2. ~/.agents/skills/ — User tool-agnostic
3. .deepagents/skills/ — Project Deep Agents Code
4. .agents/skills/ — Project tool-agnostic (highest)

When a skill is loaded, Deep Agents Code verifies that the resolved file path stays within one of these directories. Symlinks that resolve outside all skill roots are rejected. To allow symlink targets in additional directories, see [skills].extra_allowed_dirs.

Subagents

Precedence order (lowest to highest):

1. ~/.deepagents/{agent}/agents/ — User-level
2. .deepagents/agents/ — Project-level (highest)

Each subagent is an AGENTS.md file with YAML frontmatter (name, description, optional model) and a markdown body for the system prompt. See Use subagents in Deep Agents Code for the full format reference.

Instructions

All instruction sources are combined (not overridden):

1. Package base prompt (always loaded)
2. ~/.deepagents/{agent}/AGENTS.md (appended)
3. .deepagents/AGENTS.md (appended)
4. AGENTS.md at project root (appended)

.deepagents vs .agents

Directory	Purpose	When to use
.deepagents/	Deep Agents Code-specific	Skills and config that use Deep Agents Code-specific features
.agents/	Tool-agnostic	Skills you want to share across different AI CLI tools

Use .agents/skills/ for skills that work with any AI coding assistant. Use .deepagents/skills/ for skills that rely on Deep Agents-specific tools or conventions.

Cleaning up

Need	Action
Reset all data	rm -rf ~/.deepagents
Clear sessions only	rm ~/.deepagents/.state/sessions.db*
Clear input history	rm ~/.deepagents/.state/history.jsonl
Clear stored API keys	rm ~/.deepagents/.state/auth.json
Clear MCP OAuth tokens	rm -rf ~/.deepagents/.state/mcp-tokens
Clear MCP project trust	rm ~/.deepagents/.state/mcp_trust.json
Re-run first-run onboarding	rm ~/.deepagents/.state/onboarding_complete
Reset agent instructions	dcode agents reset --agent {name}
Remove a skill	rm -rf ~/.deepagents/{agent}/skills/{skill-name}

Deleting ~/.deepagents/.state/sessions.db will remove all conversation history and checkpoints.

This cannot be undone unless you have a backup of the sessions.db file.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.