Hudley.ai Agentic Studio Documentation

Stop typing code. Start directing AI agents.

Hudley is an autonomous AI development studio that transforms how you build software. Instead of manually writing every line of code, you describe features on a Kanban board and watch as AI agents powered by Claude Agent SDK automatically implement them.

1 What Makes Hudley Different?

Traditional development tools help you write code. Hudley helps you orchestrate AI agents to build entire features autonomously. Think of it as having a team of AI developers working for you—you define what needs to be built, and Hudley handles the implementation.

The Workflow

1

Add Features

Describe features you want built (with text, images, or screenshots)

2

Move to "In Progress"

Hudley automatically assigns an AI agent to implement the feature

3

Watch It Build

See real-time progress as the agent writes code, runs tests, and makes changes

4

Review & Verify

Review the changes, run tests, and approve when ready

5

Ship Faster

Build entire applications in days, not weeks

Powered by Claude Agent SDK

Hudley leverages the Claude Agent SDK to give AI agents full access to your codebase. Agents can read files, write code, execute commands, run tests, and make git commits—all while working in isolated git worktrees to keep your main branch safe.

2 Prerequisites

  • Node.js 18+ (tested with Node.js 22)
  • npm (comes with Node.js)
  • Authentication (choose one):
    • • Claude Code CLI (recommended) - Install and authenticate, credentials used automatically
    • • Anthropic API Key - Direct API key for Claude Agent SDK

3 Quick Start

After downloading and installing Hudley, launch the application. On first run, you'll see a setup wizard where you can configure authentication.

Authentication Options:

  • • Use Claude Code CLI (recommended) - Hudley will detect your CLI credentials automatically
  • • Enter an API key directly in the wizard

4 How to Run

Desktop Application

Simply download the installer for your platform (macOS, Windows, or Linux) and run it. The desktop application provides the best experience with native window management and system integration.

For Developers (Source)

If you're running from source code:

# Install dependencies
npm install
# Build shared packages
npm run build:packages
# Start the application
npm run dev

You'll be prompted to choose between Web Application (browser) or Desktop Application (Electron).

5 Authentication Setup

Option 1: Claude Code CLI (Recommended)

Install and authenticate the Claude Code CLI. Once authenticated, Hudley will automatically detect and use your CLI credentials. No additional configuration needed!

Option 2: Direct API Key

If you prefer not to use the CLI, you can provide an Anthropic API key directly using one of these methods:

Environment Variable

export ANTHROPIC_API_KEY="sk-ant-..."

.env File

ANTHROPIC_API_KEY=sk-ant-...

In-App Settings

You can also enter your API key directly in the Settings view within the application.

6 Available Views

Hudley provides several specialized views accessible via the sidebar or keyboard shortcuts:

View Shortcut Description
Board K Kanban board for managing feature workflow (Backlog → In Progress → Waiting Approval → Verified)
Agent A Interactive chat sessions with AI agents for exploratory work and questions
Spec D Project specification editor with AI-powered generation and feature suggestions
Context C Manage context files (markdown, images) that AI agents automatically reference
Profiles M Create and manage AI agent profiles with custom prompts and configurations
Settings S Configure themes, shortcuts, defaults, authentication, and more
Terminal T Integrated terminal with tabs, splits, and persistent sessions
Running Agents - View all active agents across projects with status and progress

7 Keyboard Shortcuts

All shortcuts are customizable in Settings. Default shortcuts:

Navigation

  • BoardK
  • AgentA
  • SpecD
  • ContextC
  • SettingsS
  • ProfilesM
  • TerminalT

Actions

  • Toggle Sidebar`
  • New ItemN
  • Start Next FeaturesG
  • Open ProjectO
  • Project PickerP
  • Previous ProjectQ
  • Next ProjectE

8 Core Workflow Features

📋

Kanban Board

Visual drag-and-drop board to manage features through backlog, in progress, waiting approval, and verified stages

🤖

AI Agent Integration

Automatic AI agent assignment to implement features when moved to "In Progress"

🔀

Git Worktree Isolation

Each feature executes in isolated git worktrees to protect your main branch

📡

Real-time Streaming

Watch AI agents work in real-time with live tool usage, progress updates, and task completion

🔄

Follow-up Instructions

Send additional instructions to running agents without stopping them

9 AI & Planning

🧠

Multi-Model Support

Choose from Claude Opus, Sonnet, and Haiku per feature

💭

Extended Thinking

Enable thinking modes (none, medium, deep, ultra) for complex problem-solving

📝

Planning Modes

Four planning levels: skip (direct implementation), lite (quick plan), spec (task breakdown), full (phased execution)

✅

Plan Approval

Review and approve AI-generated plans before implementation begins

📊

Multi-Agent Task Execution

Spec mode spawns dedicated agents per task for focused implementation

10 Project Management

🔍

Project Analysis

AI-powered codebase analysis to understand your project structure

💡

Feature Suggestions

AI-generated feature suggestions based on project analysis

📁

Context Management

Add markdown, images, and documentation files that agents automatically reference

🔗

Dependency Blocking

Features can depend on other features, enforcing execution order

🌳

Graph View

Visualize feature dependencies with interactive graph visualization

11 Developer Tools

🖥️

Integrated Terminal

Full terminal access with tabs, splits, and persistent sessions

🖼️

Image Support

Attach screenshots and diagrams to feature descriptions

⚡

Concurrent Execution

Configure how many features can run simultaneously (default: 3)

⌨️

Keyboard Shortcuts

Fully customizable shortcuts for navigation and actions

🎨

Theme System

25+ themes including Dark, Light, Dracula, Nord, Catppuccin, and more

🖥️

Cross-Platform

Desktop app for macOS (x64, arm64), Windows (x64), and Linux (x64)

12 How It Works

1

Feature Definition

Users create feature cards on the Kanban board with descriptions, images, and configuration

2

Git Worktree Creation

When a feature starts, a git worktree is created for isolated development

3

Agent Execution

Claude Agent SDK executes in the worktree with full file system and command access

4

Real-time Streaming

Agent output streams via WebSocket to the frontend for live monitoring

5

Plan Approval (optional)

For spec/full planning modes, agents generate plans that require user approval

6

Verification

Features move to "Waiting Approval" where changes can be reviewed via git diff

7

Integration

After approval, changes can be committed and PRs created from the worktree

13 Tech Stack

Frontend

  • React 19 - UI framework
  • Vite 7 - Build tool
  • Electron 39 - Desktop framework
  • TypeScript 5.9 - Type safety
  • TanStack Router - File-based routing
  • Zustand 5 - State management
  • Tailwind CSS 4 - Styling
  • xterm.js - Terminal emulator

Backend

  • Node.js - JavaScript runtime
  • Express 5 - HTTP server
  • TypeScript 5.9 - Type safety
  • Claude Agent SDK - AI integration
  • WebSocket (ws) - Real-time streaming
  • node-pty - Terminal sessions

14 Data Storage

Hudley uses a file-based storage system (no database required):

Per-Project Data

Stored in {projectPath}/.hudley/ 

.hudley/
├── features/              # Feature JSON files and images
│   └── {featureId}/
│       ├── feature.json   # Feature metadata
│       ├── agent-output.md # AI agent output log
│       └── images/        # Attached images
├── context/               # Context files for AI agents
├── settings.json          # Project-specific settings
├── spec.md               # Project specification
└── analysis.json         # Project structure analysis

Global Data

Stored in the application data directory:

data/
├── settings.json          # Global settings, profiles, shortcuts
├── credentials.json       # API keys (encrypted)
├── sessions-metadata.json # Chat session metadata
└── agent-sessions/        # Conversation histories

15 Security & Isolation

Important Security Note

This software uses AI-powered tooling that has access to your operating system and can read, modify, and delete files. Use at your own risk. We recommend using Hudley within a sandboxed environment or Docker container for maximum security.

🔀

Git Worktrees

Each feature executes in an isolated git worktree, protecting your main branch

📂

Path Sandboxing

Optional ALLOWED_ROOT_DIRECTORY restricts file access to specific directories

🐳

Docker Isolation

Recommended deployment uses Docker with no host filesystem access

✅

Plan Approval

Optional plan review before implementation prevents unwanted changes