> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data locations

> Where the Deep Agents CLI stores configuration, sessions, and customization files

The Deep Agents CLI 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

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
~/.deepagents/
├── .state/                  # Per-machine CLI state (managed automatically)
│   ├── sessions.db          #   SQLite database for conversation checkpoints
│   ├── history.jsonl        #   Command input history
│   ├── ...                  #   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     |
| **Base instructions**    | Package `default_agent_prompt.md`          | R          | Immutable, updated with CLI 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 deepagents
2. `~/.agents/skills/` — User tool-agnostic
3. `.deepagents/skills/` — Project deepagents
4. `.agents/skills/` — Project tool-agnostic *(highest)*

When a skill is loaded, the CLI 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`](/oss/javascript/deepagents/cli/configuration#skills-extra-allowed-directories).

### 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 the CLI](/oss/javascript/deepagents/cli/subagents) 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 CLI-specific | Skills and config that use CLI-specific features       |
| `.agents/`     | Tool-agnostic            | Skills you want to share across different AI CLI tools |

<Tip>
  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.
</Tip>

## 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`           |
| Re-run first-run onboarding | `rm ~/.deepagents/.state/onboarding_complete`      |
| Reset agent instructions    | `deepagents agents reset --agent {name}`           |
| Remove a skill              | `rm -rf ~/.deepagents/{agent}/skills/{skill-name}` |

<Warning>
  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.
</Warning>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/data-locations.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>