Skip to content
/

HumanLayer / CodeLayer

humanlayer · humanlayer/humanlayer · ★ 11k · last commit 2026-03-07

Orchestrate parallel Claude Code sessions per Linear ticket via dedicated git worktrees (MULTICLAUDE pattern) with structured research→plan→implement→PR workflows and a Tauri desktop app for session management.

Best whenPhysical worktree-per-ticket isolation + specialized read-only subagents + Linear issue lifecycle as state machine is the correct architecture for team-scale…
Skip ifSMALL or XS only (large tickets must be broken down before ralph), Blind directory scanning
vs seeds
claude-flow(Archetype 3, MCP-anchored toolserver with parallel multi-agent) but adds physical worktree-per-ticket isolation, Linear…
Primitive shape 34 total
Commands 27 Subagents 6 MCP tools 1
00

Summary

humanlayer — HumanLayer / CodeLayer

HumanLayer (now rebranding as "CodeLayer") is an open-source IDE built on Claude Code that provides keyboard-first workflows for AI-assisted development, with a particular focus on multi-Claude parallel execution and advanced context engineering. The monorepo contains a Tauri+React desktop app (CodeLayer WUI), a Go daemon (hld) that coordinates approvals and manages Claude Code sessions, a TypeScript CLI with MCP server (hlyr), a Go SDK for launching Claude Code sessions (claudecode-go), and the original HumanLayer SDK (TypeScript + Go) for human-in-the-loop capabilities. The framework's distinguishing contribution is the "MULTICLAUDE" pattern — parallel Claude Code sessions in separate git worktrees, orchestrated by the ralph_* command set. The Claude Code command suite includes 27 commands with a clear workflow: research → plan → implement → review → commit → PR, plus a distinct ralph execution loop.

Compared to the seeds, HumanLayer is closest to claude-flow (Archetype 3 — MCP-anchored toolserver) in its daemon architecture (hld), MCP server (hlyr), and parallel multi-agent execution. The key delta is the local desktop UI (CodeLayer WUI) and the structured worktree-per-ticket workflow tied to Linear issue tracking.

01

Overview

Overview — HumanLayer / CodeLayer

Origin

HumanLayer started as an SDK for human-in-the-loop AI agent approvals (Slack, email, CLI-based approval channels) and has evolved into CodeLayer — a full IDE experience built on Claude Code. The team is described as "leading experts on getting the most out of today's models" and has given talks at YC on "Advanced Context Engineering for Coding Agents" and authored "12 Factor Agents."

Philosophy

From README:

"Superhuman for Claude Code - Keyboard-first workflows designed for builders who value speed and control."

"Advanced Context Engineering - Scale AI-first dev to your entire team, without devolving into a chaotic slop-fest."

"M U L T I C L A U D E - Run Claude Code sessions in parallel. Worktrees? Done. Remote cloud workers? You got it."

From ralph_impl.md command:

"set up worktree for implementation... launch implementation session: humanlayer-nightly launch --model opus --dangerously-skip-permissions --dangerously-skip-permissions-timeout 15m"

Key Concepts

  • Ralph workflow: A continuous autonomous execution loop where Claude works through a queue of Linear tickets (research → plan → implement → PR) without human checkpoints per step
  • MULTICLAUDE: Parallel Claude Code sessions in separate git worktrees — one agent per ticket
  • Thoughts: A shared filesystem layer (./thoughts/) for cross-session context persistence and Linear ticket sync
  • Context Engineering: Curated agent specialization (codebase-analyzer, codebase-locator, pattern-finder, web-search-researcher)

User Testimonials (README)

"Our entire company is using CodeLayer now. We're shipping one banger PR after the other." — René Brandel, Founder @ Casco (YC X25)

"This has improved my productivity (and token consumption) by at least 50%." — Tyler Brown, Founder @ Revlo.ai

02

Architecture

Architecture — HumanLayer / CodeLayer

Distribution

  • Type: npm-package (monorepo, multiple packages)
  • Primary install: npx humanlayer join-waitlist --email ... (CodeLayer WUI — early access waitlist)
  • SDK install: npm install @humanlayer/sdk (TypeScript SDK)
  • Build: make setup, make check-test

Monorepo Structure

humanlayer/
├── .claude/
│   ├── commands/           # 27 slash commands
│   ├── agents/             # 6 specialized subagents
│   └── settings.json
├── CLAUDE.md               # Repository guidance
├── apps/                   # Application packages
├── hld/                    # Go daemon: approval coordination, session management
├── hlyr/                   # TypeScript CLI + MCP server
├── humanlayer-wui/         # CodeLayer desktop app (Tauri + React)
│   └── src-tauri/          # Tauri Rust backend
├── claudecode-go/          # Go SDK for launching Claude Code sessions
├── packages/               # humanlayer-ts, humanlayer-go, etc.
│   ├── humanlayer-ts/      # TypeScript SDK
│   ├── humanlayer-go/      # Go client
│   └── humanlayer-ts-vercel-ai-sdk/  # Vercel AI SDK integration
├── docs/                   # Mintlify documentation
├── Makefile                # Build/test orchestration
└── turbo.json              # Turborepo build config

Architecture Flow (from CLAUDE.md)

Claude Code → MCP Protocol → hlyr → JSON-RPC → hld → HumanLayer Cloud API
                                         ↑         ↑
                                    TUI ─┘         └─ WUI

CodeLayer WUI (Tauri + React)

  • Tech stack: Tauri (Rust backend) + React + TypeScript + Radix UI + Vite
  • Purpose: Desktop app for graphical approval management, parallel session monitoring
  • Key deps: @humanlayer/hld-sdk, Radix UI components, Sentry, Storybook

Required Runtime

  • Node.js (bun or npm)
  • Go 1.21–1.24 (for hld, claudecode-go)
  • Tauri (for desktop WUI builds)
  • Claude Code CLI (for agent execution)

Target AI Tools

Claude Code (primary, deep integration), with the original HumanLayer SDK supporting any LLM framework via TypeScript/Go SDKs.

03

Components

Components — HumanLayer / CodeLayer

Slash Commands (27, in .claude/commands/)

Command Purpose
ci_commit.md CI-specific commit creation
ci_describe_pr.md CI-specific PR description
commit.md Create commit
create_handoff.md Create cross-session handoff document
create_plan.md Create implementation plan
create_plan_generic.md Generic plan creation
create_plan_nt.md Plan creation (no-ticket variant)
create_worktree.md Set up git worktree for a ticket
debug.md Debug workflow
describe_pr.md Describe PR with Linear ticket context
describe_pr_nt.md PR description (no-ticket variant)
founder_mode.md Founder mode workflow
implement_plan.md Implement from plan document
iterate_plan.md Iterate on existing plan
iterate_plan_nt.md Plan iteration (no-ticket variant)
linear.md Linear issue management
local_review.md Local code review
oneshot.md Research ticket + launch planning session in parallel
oneshot_plan.md Plan from ticket in one shot
ralph_impl.md Ralph: implement highest priority small ticket with worktree
ralph_plan.md Ralph: create implementation plan for highest priority ticket
ralph_research.md Ralph: research ticket context
research_codebase.md Research codebase patterns
research_codebase_generic.md Generic codebase research
research_codebase_nt.md Research (no-ticket variant)
resume_handoff.md Resume from handoff document
validate_plan.md Validate plan completeness

Specialized Subagents (6, in .claude/agents/)

Agent Tools Purpose
codebase-analyzer.md Read, Grep, Glob, LS Analyze HOW code works — implementation details, data flow, design patterns. Read-only, no suggestions unless asked.
codebase-locator.md Read, Grep, Glob, LS Find WHERE things are — file locations, function definitions, usage sites. Fast directory search.
codebase-pattern-finder.md Read, Grep, Glob, LS Find patterns and conventions — naming, structure, anti-patterns. Infer team standards.
thoughts-analyzer.md Read, Grep, Glob, LS Analyze thoughts/ directory — past decisions, prior research, context.
thoughts-locator.md Read, Grep, Glob, LS Find relevant thoughts/ files for a task.
web-search-researcher.md WebFetch, Grep External documentation and library research.

Key Infrastructure Components

Component Language Purpose
hld Go Daemon: approval coordination, Claude Code session management
hlyr TypeScript CLI + MCP server: agent-facing tools
claudecode-go Go SDK for programmatically launching Claude Code sessions
humanlayer-ts TypeScript Core HumanLayer SDK
humanlayer-go Go Minimal Go client
CodeLayer WUI Tauri+React Desktop app for graphical management

State Files

Path Purpose
./thoughts/shared/tickets/ENG-<id>.md Linear ticket context (fetched via CLI)
./thoughts/shared/plans/YYYY-MM-DD-ENG-<id>-<desc>.md Implementation plans
~/wt/humanlayer/ENG-<id>/ Git worktrees per ticket

Hooks

None (.claude/settings.json doesn't define hook events — confirmed by absence of hooks key).

05

Prompts

Prompts — HumanLayer / CodeLayer

Excerpt 1: ralph_impl — Autonomous Worktree + Parallel Session Launch

Source: .claude/commands/ralph_impl.md Technique: Structured ticket workflow with automatic worktree creation and parallel session launch

---
description: Implement highest priority small Linear ticket with worktree setup
model: sonnet
---

## PART I - IF NO TICKET IS MENTIONED

0.  read .claude/commands/linear.md
0a. fetch the top 10 priority items from linear in status "ready for dev" using the MCP tools, noting all items in the `links` section
0b. select the highest priority SMALL or XS issue from the list (if no SMALL or XS issues exist, EXIT IMMEDIATELY and inform the user)
0c. use `linear` cli to fetch the selected item into thoughts with the ticket number - ./thoughts/shared/tickets/ENG-xxxx.md
0d. read the ticket and all comments to understand the implementation plan and any concerns

## PART II - NEXT STEPS

think deeply

1. move the item to "in dev" using the MCP tools
1a. identify the linked implementation plan document from the `links` section
1b. if no plan exists, move the ticket back to "ready for spec" and EXIT with an explanation

think deeply about the implementation

2. set up worktree for implementation:
2a. read `hack/create_worktree.sh` and create a new worktree with the Linear branch name: `./hack/create_worktree.sh ENG-XXXX BRANCH_NAME`
2b. launch implementation session: `humanlayer-nightly launch --model opus --dangerously-skip-permissions --dangerously-skip-permissions-timeout 15m --title "implement ENG-XXXX" -w ~/wt/humanlayer/ENG-XXXX "/implement_plan and when you are done implementing and all tests pass, read ./claude/commands/commit.md and create a commit, then read ./claude/commands/describe_pr.md and create a PR, then add a comment to the Linear ticket with the PR link"`

think deeply, use TodoWrite to track your tasks. When fetching from linear, get the top 10 items by priority but only work on ONE item - specifically the highest priority SMALL or XS sized issue.

Excerpt 2: codebase-analyzer — Strict Read-Only Research Agent

Source: .claude/agents/codebase-analyzer.md Technique: Specialized read-only subagent with explicit prohibition on suggestions/improvements

---
name: codebase-analyzer
description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components.
tools: Read, Grep, Glob, LS
model: sonnet
---

You are a specialist at understanding HOW code works.

## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
- DO NOT suggest improvements or changes unless the user explicitly asks for them
- DO NOT perform root cause analysis unless the user explicitly asks for them
- DO NOT propose future enhancements unless the user explicitly asks for them
- DO NOT critique the implementation or identify "problems"
- DO NOT comment on code quality, performance issues, or security concerns
- DO NOT suggest refactoring, optimization, or better approaches
- ONLY describe what exists, how it works, and how components interact

Excerpt 3: oneshot — Parallel Research + Planning

Source: .claude/commands/oneshot.md Technique: Sub-session spawning for parallel concurrent execution

---
description: Research ticket and launch planning session
---

1. use SlashCommand() to call /ralph_research with the given ticket number
2. launch a new session with `npx humanlayer launch --model opus --dangerously-skip-permissions --dangerously-skip-permissions-timeout 14m --title "plan ENG-XXXX" "/oneshot_plan ENG-XXXX"`
09

Uniqueness

Uniqueness — HumanLayer / CodeLayer

Differs From Seeds

HumanLayer is closest to claude-flow (Archetype 3 — MCP-anchored toolserver) in its daemon architecture (hld), MCP server (hlyr), and parallel multi-agent execution. The key deltas: (1) local desktop UI — CodeLayer WUI (Tauri+React) provides a graphical session manager that no seed has; (2) structured worktree-per-ticket — the ralph workflow physically isolates each ticket to its own git worktree on disk at ~/wt/humanlayer/ENG-<id>/, stronger than claude-flow's git-branch isolation; (3) Linear-native — the entire workflow is tied to Linear issue management (ready for spec → plan in review → in dev → shipped), with ticket status driving phase transitions; (4) specialized read-only subagents — 6 purpose-built subagents with explicit tool restrictions (Read/Grep/Glob/LS only) rather than generalist spawned agents; (5) original human-in-the-loop SDK — the multi-channel approval system (Slack, email, CLI) is a unique primitive not present in any seed.

Positioning

HumanLayer occupies the "team-scale Claude Code orchestration" niche. It is designed for small engineering teams (founders + engineers) who want to run multiple Claude Code agents in parallel against a Linear backlog, with structured handoffs and PR automation. The CodeLayer WUI and ralph workflow together constitute a distinct product vision: "Superhuman for Claude Code."

Observable Failure Modes

  1. Linear dependency: The ralph workflow is deeply tied to Linear — teams using Jira, GitHub Issues, or other trackers need significant adaptation
  2. Waitlist friction: CodeLayer WUI is not yet publicly available; the full product vision is blocked by early access
  3. --dangerously-skip-permissions: The ralph_impl launch command uses this flag — aggressive autonomy that could cause unintended writes in production repos
  4. 14-15 minute timeouts: Parallel sessions expire after 14-15 minutes; long implementations get cut off
  5. Worktree proliferation: Many parallel tickets create many worktrees at ~/wt/humanlayer/; no documented cleanup strategy
  6. Sonnet vs Opus routing: ralph_impl defaults to Sonnet; oneshot/ralph_plan use Opus — inconsistent model routing across the same workflow
04

Workflow

Workflow — HumanLayer / CodeLayer

Ralph Workflow (Autonomous Execution Loop)

The Ralph pattern automates the full development cycle from Linear ticket to merged PR:

/ralph_research → /ralph_plan → /ralph_impl

ralph_research

  1. Fetch ticket from Linear using MCP tools
  2. Write ticket context to ./thoughts/shared/tickets/ENG-<id>.md
  3. Research codebase for relevant patterns

ralph_plan

  1. Fetch top-10 priority items from Linear (status: "ready for spec")
  2. Select highest priority SMALL or XS issue
  3. Fetch ticket into ./thoughts/shared/tickets/ENG-<id>.md
  4. Create implementation plan at ./thoughts/shared/plans/YYYY-MM-DD-ENG-<id>-<desc>.md
  5. Sync thoughts and attach plan to Linear ticket
  6. Move ticket to "plan in review" status

ralph_impl

  1. Fetch top-10 priority items from Linear (status: "ready for dev")
  2. Select highest priority SMALL or XS issue
  3. Move ticket to "in dev"
  4. Create worktree: ./hack/create_worktree.sh ENG-XXXX BRANCH_NAME
  5. Launch parallel session: humanlayer-nightly launch --model opus --dangerously-skip-permissions --dangerously-skip-permissions-timeout 15m -w ~/wt/humanlayer/ENG-XXXX "/implement_plan and when done: create commit, create PR, add comment to Linear ticket with PR link"

Oneshot Workflow (Fast Track)

/oneshot
  1. /ralph_research with ticket number
  2. Launch parallel planning session: npx humanlayer launch --model opus --title "plan ENG-XXXX" "/oneshot_plan ENG-XXXX"

Phase-to-Artifact Map

Phase Artifact
ralph_research ./thoughts/shared/tickets/ENG-<id>.md
ralph_plan ./thoughts/shared/plans/<date>-ENG-<id>-<desc>.md
create_worktree ~/wt/humanlayer/ENG-<id>/ (git worktree)
implement_plan Code changes in worktree
commit Git commit in worktree
describe_pr PR on GitHub + comment on Linear ticket

Approval Gates

  1. Plan review: Plan must exist in thoughts/ before ralph_impl proceeds ("if no plan exists, move ticket back to 'ready for spec' and EXIT")
  2. Test passage: /implement_plan loop: "when done implementing and all tests pass, create commit"
  3. Size gate: Ralph only works on SMALL or XS issues ("if no SMALL or XS issues exist, EXIT IMMEDIATELY")

Linear Integration

  • Ticket lifecycle: ready for spec → plan in progress → plan in review → ready for dev → in dev → PR created
  • linear CLI used directly in commands (e.g., linear fetch ENG-<id>)
  • MCP tools for Linear (read + write operations on tickets and comments)
06

Memory Context

Memory & Context — HumanLayer / CodeLayer

Thoughts Filesystem

The primary shared context layer is ./thoughts/:

./thoughts/
└── shared/
    ├── tickets/
    │   └── ENG-<id>.md          # Linear ticket context (fetched via CLI)
    └── plans/
        └── YYYY-MM-DD-ENG-<id>-<desc>.md  # Implementation plans

humanlayer thoughts sync syncs the thoughts directory (likely to a shared remote or Git repo for team use).

Cross-Session Handoff

The create_handoff.md and resume_handoff.md commands provide explicit cross-session context transfer. Handoff documents capture: what was done, what's next, open questions.

Worktree Isolation

Each ticket gets its own git worktree at ~/wt/humanlayer/ENG-<id>/. The thoughts directory is accessible from all worktrees (shared parent path).

Linear as External State

Linear issue lifecycle (ready for spec → plan in review → ready for dev → in dev → PR created) serves as the external state machine. Commands read and write Linear ticket status as part of the workflow.

MCP Server (hlyr)

hlyr exposes Claude Code tools via MCP, providing the agent with access to hld (the approval daemon) and potentially Linear/GitHub integrations.

HumanLayer Cloud (Legacy SDK)

The original HumanLayer SDK provides human-in-the-loop approval channels:

  • Slack: approval requests sent to Slack, responses trigger agent continuation
  • Email: email-based approval flow
  • CLI: local terminal approval
  • Web (hld + WUI): local daemon + Tauri desktop app approval UI

Compaction

No explicit compaction strategy documented in the command files. The Read-Once pattern is used implicitly (plans are read once per session, not re-read).

07

Orchestration

Orchestration — HumanLayer / CodeLayer

Multi-Agent Support

Yes — MULTICLAUDE is a first-class feature:

  • Multiple Claude Code sessions run in parallel, each in a separate git worktree
  • ralph_impl launches new sessions via humanlayer-nightly launch
  • oneshot spawns a parallel planning session alongside a research session

Orchestration Pattern

Parallel fan-out — one orchestrator (ralph) dispatches implementation sessions per ticket, each in its own worktree. Sessions run independently and submit PRs.

Subagents

6 specialized read-only subagents in .claude/agents/:

  • All run with restricted tool sets (Read, Grep, Glob, LS only)
  • Invoked by main agent for specialized research tasks
  • Defined as persona-md files with explicit tool restrictions and behavioral constraints

Isolation Mechanism

Git worktree per feature (ticket). Each ralph_impl creates a worktree at ~/wt/humanlayer/ENG-<id>/. This is the strongest isolation pattern in the seeds corpus (physical filesystem isolation, not just branch isolation).

Multi-Model Support

Partially documented:

  • ralph_impl.md: model: sonnet in frontmatter
  • oneshot.md: --model opus explicitly passed to humanlayer launch
  • The framework explicitly routes higher-reasoning tasks to Opus

Execution Mode

Continuous-ralph — ralph_plan and ralph_impl are designed to be invoked in a loop, picking up the next ticket each time. The system is designed for autonomous marathon runs.

Crash Recovery

Yes — through git worktrees (work persists in filesystem) and Linear ticket state (ticket reverts to previous status if plan/impl fails).

Consensus Mechanism

None — parallel agents work on different tickets independently.

Prompt Chaining

Yes — research output → plan creation → implementation → commit → PR is a chain where each step reads the previous step's output.

Human-in-the-Loop (Legacy SDK)

The original HumanLayer SDK provided structured human approval channels:

  • Agent calls HumanLayer API with an approval request
  • Human approves via Slack/email/CLI/WUI
  • Agent continues after approval
  • Architecture: Claude Code → hlyr (MCP) → hld (daemon) → HumanLayer Cloud API → Slack/email
08

Ui Cli Surface

UI & CLI Surface — HumanLayer / CodeLayer

CodeLayer WUI (Desktop App)

Yes — Tauri + React desktop application.

  • Tech stack: Tauri (Rust) + React + TypeScript + Radix UI + Vite
  • Key deps: @humanlayer/hld-sdk, Radix UI (checkbox, dialog, dropdown, label, popover, scroll-area, select, slot, switch, tabs, tooltip), Sentry, Storybook
  • Purpose: Graphical approval management, parallel Claude Code session monitoring
  • Features (inferred from deps):
    • approval request queue
    • multi-session monitor
    • keyboard-first navigation (Storybook for component dev)
  • Status: In development (currently waitlist-only)

humanlayer CLI (npx humanlayer)

  • npx humanlayer join-waitlist --email <email> — waitlist registration
  • humanlayer-nightly launch --model opus --dangerously-skip-permissions --dangerously-skip-permissions-timeout 14m --title "..." -w <worktree> "/command" — launch parallel Claude Code session in worktree

hld TUI

hld (Go daemon) provides a TUI for local approval management alongside the WUI option.

IDE Integration

Built on Claude Code — no separate IDE extension. Works within Claude Code's existing interface plus the standalone WUI for session management.

Slash Commands as UI

27 slash commands provide the primary interaction surface within Claude Code. The Ralph workflow is a keyboard-first sequence: /ralph_research, /ralph_plan, /ralph_impl.

Observability

  • Linear ticket status as external state machine
  • ./thoughts/ directory as shared audit trail of plans and decisions
  • humanlayer thoughts sync for team-shared context
  • GitHub PRs + Linear comments as output artifacts
  • No structured JSONL log or dedicated audit trail

Developer Tooling

  • Makefile with make setup, make check-test, make check, make test
  • biome.jsonc for TypeScript linting
  • Turborepo for monorepo build orchestration

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…