Deep

What is Deep?

LangChain's deepagents gives you the architectural patterns behind tools like Claude Code and Deep Research — planning, filesystem abstractions, subagent spawning, persistent memory — packaged as a Python library.

What it doesn't give you is a way to actually use it. No terminal UI. No model switching. No way to plug in your Anthropic or Google credentials. No OAuth. No plugin system. No MCP integration.

Deep is everything that's missing. A full terminal interface and operability layer built on top of deepagents, turning it from a framework into a daily-driver coding agent. Inspired by pi-mono's approach to extensible agent tooling.

The Two-Layer Architecture

Everything above the deepagents layer is this repo. Everything below is upstream. The coupling is intentionally narrow — one file (agent.py) calls create_deep_agent(), uses CompositeBackend, and wires in middleware. If LangChain changes those interfaces, you update one file.

What We Added (vs Upstream)

What we didn't change: the base deepagents package. We call create_deep_agent(), use its CompositeBackend, MemoryMiddleware, SkillsMiddleware, and subagent system exactly as designed. No monkey-patching, no vendored copies.

How It Works

uv pip install -e .
deepagents

The Background Task System

This is one of the more interesting pieces. The base deepagents library blocks when a subagent runs — your main agent sits idle waiting for the result. We solved this without touching upstream:

task tool call
  ↓
BackgroundTaskMiddleware intercepts via awrap_tool_call
  ↓
Spawns as asyncio.Task via BackgroundTaskManager
  ↓
Returns immediate ToolMessage with tracking ID
  ↓
Agent continues working
  ↓
check_task(id) / wait_for_task(id) / list_background_tasks
  ↓
UI shows live agent pill + toast on completion

The middleware registers companion tools automatically — the framework picks them up via getattr(m, "tools", []). Zero changes to deepagents internals. HITL approval still fires before the middleware intercepts, so you still approve the launch.

Memory and Skills

Deep uses a layered filesystem approach for context — project-scoped overrides user-scoped:

~/.deepagents/<agent>/
  AGENTS.md              # Agent-level persistent context

<project>/.deepagents/
  AGENTS.md              # Project-scoped context (overrides)

~/.deepagents/<agent>/skills/<skill>/
  SKILL.md               # Reusable skill definition

<project>/.deepagents/skills/<skill>/
  SKILL.md               # Project-specific skills

~/.deepagents/<agent>/subagents/<n>/
  AGENTS.md              # Subagent system prompt

<project>/.deepagents/subagents/<n>/
  AGENTS.md              # Project-scoped override

---
skills:
  - web-research
  - code-review
---

Extensions

Extensions are Python modules that plug into the agent lifecycle:

# ~/.deepagents/extensions/my_ext.py
def register(ctx):
    ctx.add_tool(my_custom_tool)
    ctx.add_middleware(MyMiddleware())
    ctx.add_command("/mycommand", handler)
    ctx.on("tool_call", my_hook)

Extensions can register tools, middleware, commands, subagent specs, and event hooks. They're discovered from ~/.deepagents/extensions/ and <project>/.deepagents/extensions/, or declared explicitly in settings.

Built-in: Linear (deepagents_cli.ext.linear) — powers the /assemble pipeline (scout → planner → worker → reviewer on Linear issues).

Model Configuration

{
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com/v1",
      "api": "openai-responses",
      "models": [
        { "id": "gpt-5.2", "alias": "primary", "reasoning": "high" }
      ]
    },
    "anthropic": {
      "api": "anthropic-messages",
      "models": [
        { "id": "claude-sonnet-4-5-20250929", "alias": "sonnet" }
      ]
    }
  }
}

{
  "openai": { "type": "api_key", "key": "sk-..." },
  "anthropic": { "type": "oauth", "access_token": "...", "refresh_token": "..." }
}

{
  "model": {
    "active": { "provider": "openai", "id": "gpt-4o" },
    "reasoning": "high",
    "service_tier": "priority"
  }
}

CLI Reference

deepagents                              # Interactive TUI
deepagents --agent mybot                # Named agent profile
deepagents --model openai:gpt-5.2      # Override model
deepagents --reasoning medium           # Override reasoning effort
deepagents --no-auto-approve            # Require all tool approvals
deepagents --no-thread-lock             # Disable session locking

Type @ to fuzzy-search project files. Type / to browse commands.

What Makes This Different

Tech Stack

Install

# With uv (recommended)
uv pip install -e .

# Or pip
pip install -e .

# Run
deepagents

References

• deepagents — LangChain's deep agent framework (upstream): GitHub
• pi-mono — Extensible agent toolkit inspiration: GitHub
• LangGraph — Stateful agent orchestration: docs
• Model Context Protocol — Tool server standard: modelcontextprotocol.io
• Textual — Terminal UI framework: textual.textualize.io
• Noktua — The desktop GUI sibling (same patterns, Electron UI): Noktua docs
• Xena — The webhook-first sibling (autonomous operations): Xena docs