hammoc

Kick Back. Tap. Ship.
The web IDE built for AI-driven development workflows — starting with BMAD-METHOD.

User Manual · Quick Start · Features

What is Hammoc?

Hammoc is a web IDE optimized for structured AI-driven development methodologies. It currently provides first-class support for the BMAD-METHOD V4 workflow — with plans to support additional methodologies in the future.

Built on top of Claude Code, Hammoc provides everything you need to run a full BMAD workflow from your browser: agent switching, PRD-to-queue automation, epic/story tracking, and a Kanban board — all in one place. No terminal hopping, no context switching.

Fully responsive and mobile-first. Kick back in your hammock, tap a command on your phone, and let the AI ship it. Inspired by Rich Hickey's Hammock Driven Development — the idea that real breakthroughs come when you step back, not when you're grinding at the terminal.

Quick Start

Prerequisites

• Node.js >= 18.0.0 (v22 LTS recommended)
• Claude Code CLI installed and authenticated (claude --version)

Install & Run

# Run directly (no install needed)
npx hammoc

# Or install globally
npm install -g hammoc
hammoc

Open http://localhost:3000 in your browser. First launch guides you through password setup and CLI verification.

CLI Options

hammoc [options]

Options:
  --port <number>        Port to listen on (default: 3000, env: PORT)
  --host <string>        Host to bind to (default: 0.0.0.0, env: HOST)
  --trust-proxy          Enable reverse proxy support (env: TRUST_PROXY)
  --cors-origin <url>    Restrict CORS to specific origin (env: CORS_ORIGIN)
  --rate-limit <number>  Requests per minute per IP (default: 200, env: RATE_LIMIT)
  --reset-password       Reset the admin password
  -h, --help             Show this help message
  -v, --version          Show version number

Mobile Access

Fully responsive. Access from your phone or tablet at http://<your-ip>:3000 on the same network.

PWA (Progressive Web App)

Hammoc can be installed as a standalone app on your PC or mobile device.

• PC (localhost): Open http://localhost:3000 in Chrome → click the install icon in the address bar. No extra setup needed.
• Mobile (local network): Requires HTTPS. See the HTTPS Setup section below.

⚠️ Security Notice

Hammoc is designed for local network / VPN use. While it includes security hardening for external exposure (see Remote Access below), it has not undergone a formal security audit. For maximum safety, run behind a trusted VPN (e.g., Tailscale, WireGuard).

Remote Access

If you need to expose Hammoc through a reverse proxy (Cloudflare Tunnel, nginx, etc.):

npx hammoc --trust-proxy --cors-origin https://hammoc.yourdomain.com

This enables:

• Proxy header support — Correctly identifies client IPs behind the proxy (CF-Connecting-IP, X-Forwarded-For, X-Real-IP)
• Secure cookies — Session cookies are set with Secure flag for HTTPS
• CORS restriction — Only the specified origin can make authenticated requests
• Rate limiting — 200 requests/min per IP (adjust with --rate-limit)

Security features (always active):

• Helmet.js security headers (CSP, X-Frame-Options, HSTS, X-Content-Type-Options)
• Server management APIs restricted to loopback only (127.0.0.1)
• Terminal access restricted to local network IPs
• IP validation with strict format checking and net.isIP() verification
• XFF spoofing protection (rightmost IP parsing)
• Debug endpoints disabled in production

Features

Why Hammoc?

	Hammoc	Terminal-based IDE	Generic Web IDE
BMAD-METHOD workflow	Built-in	Manual	N/A
Agent switching (SM, PM, Dev, QA...)	One tap	CLI commands	N/A
PRD → Queue automation	Auto-generate	Copy-paste	N/A
Mobile development	Full support	Limited	Partial
Kanban + Epic tracking	Integrated	Separate tool	Separate tool

Chat Interface

Real-time conversations with Claude through a rich web UI.

• Streaming responses — Messages appear progressively as Claude generates them
• Markdown rendering — Full markdown support with syntax-highlighted code blocks and copy buttons
• Image attachments — Attach up to 5 images (PNG, JPEG, GIF, WebP) per message with thumbnail display
• Tool call visualization — See what tools Claude uses, with inputs, outputs, and execution time
• Diff viewer — Side-by-side file diff display for code changes
• Extended thinking — View Claude's reasoning process in collapsible blocks
• Message edit — Edit previous messages to branch the conversation into alternative paths
• Summarize & Continue — Compress long conversations with AI-generated summaries
• Code rewind — Restore project files to any earlier point in the conversation
• Session fork — Branch into a new session from any assistant response
• Conversation branching — Navigate between branches with pagination controls, and browse all branches in a read-only viewer
• Prompt history — Navigate previous inputs with arrow keys
• Prompt chaining — Queue up to 10 prompts for sequential execution (server-synced, multi-browser)
• Voice input — Dictate messages using browser speech recognition (Chrome, Edge, Safari)
• Context usage monitor — Track token usage and cost in real-time
• Abort generation — Stop responses with the abort button or ESC key

Session Management

• Session list — Browse past conversations with preview, message count, and date
• Session search — Search by name or conversation content (server-side)
• Session renaming & deletion — Keep conversations organized
• Quick session panel — Access sessions without leaving the chat
• Active streaming indicator — See which sessions are currently active

Slash Commands, Snippets & Favorites

• Command palette — Type / to browse available commands with autocomplete
• Prompt snippets — Type % to insert reusable prompt templates with argument substitution, context blocks, and multi-prompt chaining
• Snippet hierarchy — Project, global, and bundled snippets with override support
• Favorites bar — Pin up to 20 frequently used commands above the input
• Star favorites — Mark up to 10 star commands for quick access
• Drag-to-reorder — Customize favorite command order
• Agent-specific commands — Context-aware commands per BMad agent

Model & Permission Control

• Model selector — Choose between Claude Sonnet, Opus, and Haiku variants
• Thinking effort — Adjust reasoning intensity (Low / Medium / High / Max on Opus 4.6)
• Permission modes — Plan, Ask (default), Auto, or Bypass
• Per-project overrides — Different settings per project

Project Management

• Project list — Browse all projects with session counts and last activity
• Project dashboard — Real-time status: active chats, queue runners, terminals
• Project creation — Create new projects with optional BMad Method initialization
• Project settings — Per-project model, permission, system prompt, and budget configuration
• Hide/unhide projects — Keep the list clean

File Explorer & Editor

• Grid & List views — Finder-style grid or traditional list layout
• Tree navigation — Directory hierarchy with breadcrumbs
• Text editor — Syntax highlighting with save (Ctrl+S)
• Markdown preview — Toggle between edit and preview modes
• Image viewer — Full-screen image viewing with zoom controls and multi-image navigation
• File operations — Create, rename, and delete files and folders

Git Integration

• Status panel — Staged, unstaged, and untracked changes at a glance
• Stage & commit — Stage files individually or all at once, write commit messages
• Branch management — Create, switch, and view branches
• Pull & Push — Sync with remote repositories
• Quick Git panel — Lightweight Git access from the chat view

Terminal

• PTY emulation — Full terminal emulation powered by xterm.js
• Multiple tabs — Run several terminal sessions simultaneously
• Security — Restricted to local network by default; configurable via settings

Queue Runner (Batch Automation)

Automate repetitive prompt sequences.

• Queue editor — Write prompt sequences line by line
• Special commands — @new, @save, @load, @pause, @model, @delay, @(/@), # comments
• Execution control — Start, pause (deferred), resume, abort, and edit remaining items while paused
• Templates — Save and load reusable queue scripts
• Story-based generation — Auto-generate queue from PRD epics and stories
• Variable substitution — Use {story_num}, {epic_num}, {story_index}, {story_title}, {date} in templates

Project Board (Issue Tracking)

• Kanban board — Visual cards across customizable status columns
• List view — Tabular alternative with sorting and filtering
• Issue types — Bug, Improvement
• Severity levels — Low, Medium, High, Critical
• Status workflow — Open → Draft → Approved → In Progress → Blocked → Review → Done → Closed
• Mobile Kanban — Touch-optimized board for small screens

Settings

• Theme — Dark, Light, or System
• Language — English, 中文, 日本語, 한국어, Español, Português
• Chat timeout — 1m, 3m, 5m (default), 10m, 30m
• Web Push & Telegram notifications — Get notified on permission requests, completions, and errors
• System prompt editing — Customize Claude's behavior per project
• Advanced — Server restart, software updates, SDK parameters (thinking tokens, turns, budget)

BMAD-METHOD V4 Integration

Hammoc is the most convenient way to run a full BMAD-METHOD (Breakthrough Method for Agile AI-Driven Development) workflow. Every step — from project inception to QA — is built into the IDE.

• One-click BMad setup — Initialize .bmad-core in any project with version selection
• BMad Agent switching — Instantly switch between agents (SM, PM, Architect, Dev, QA, PO, etc.) in chat with a single tap
• Slash commands per agent — Context-aware /commands that change based on the active BMad agent
• PRD → Queue automation — Auto-generate prompt queues directly from your PRD epics and stories
• Project overview dashboard — Visual status showing PRD completion, epic progress, and story status
• Kanban board integration — Track epics and stories with status workflow, promote/validate actions
• Story workflows — Start development, request QA, and apply fixes — all through the board UI

Methodology support roadmap: Hammoc is designed to be methodology-agnostic. BMAD-METHOD V4 is the first supported workflow, with more development methodologies planned for future releases.

For detailed BMAD-METHOD documentation, visit the official repository.

Keyboard Shortcuts

Shortcut	Action
Enter	Send message (desktop)
Shift+Enter	New line in message
ESC	Abort generation
Ctrl+S	Save file in editor
Ctrl+= Ctrl+-	Terminal font size
Ctrl+0	Reset terminal font size
%	Open snippet autocomplete palette
↑ / ↓	Navigate prompt history
Alt+1/2/3/4	Toggle quick panel (Sessions/Files/Git/Terminal)

Architecture

Hammoc is a monorepo with three packages:

hammoc/
├── bin/hammoc.js             # CLI entry point
├── packages/
│   ├── shared/                    # Shared types, constants, utilities
│   ├── server/                    # Express + Socket.io backend
│   └── client/                    # React + Vite frontend
└── scripts/
    └── postinstall.cjs            # Shared package linker

Tech Stack:

• Frontend: React 18, Vite, Tailwind CSS, Zustand, Socket.io Client, xterm.js
• Backend: Node.js, Express, Socket.io, node-pty, Claude Agent SDK
• Shared: TypeScript, Zod validation

Development

git clone https://github.com/starsh2001/hammoc.git
cd hammoc
npm install
npm run dev

Command	Description
npm run dev	Start all packages in development mode
npm run build	Build all packages for production
npm start	Run server in production mode
npm test	Run all tests
npm run lint	Run ESLint on all packages
npm run typecheck	Run TypeScript type checking

Data Storage

Data	Location
App config & password	~/.hammoc/config.json
User preferences	~/.hammoc/preferences.json
Queue templates	<project-root>/.hammoc/queue-templates.json (per project)
Chain failures	~/.hammoc/chain-failures/<sessionId>.json (per session)
Snippets (global)	~/.hammoc/snippets/ (shared across projects)
Snippets (project)	<project-root>/.hammoc/snippets/ (per project)
TLS certificates	~/.hammoc/cert.pem, ~/.hammoc/key.pem
Session data	~/.claude/projects/ (managed by Claude Code CLI)

HTTPS Setup (for Mobile PWA)

PWA installation on mobile devices requires HTTPS. Hammoc automatically starts in HTTPS mode when TLS certificates are found at ~/.hammoc/cert.pem and ~/.hammoc/key.pem. If no certificates are found, it falls back to HTTP.

Option 1: mkcert (Recommended)

• Install mkcert:

  # Windows
  winget install FiloSottile.mkcert
  
  # macOS
  brew install mkcert
  
  # Linux
  # See https://github.com/FiloSottile/mkcert#installation
  

• Create a local CA and generate certificates:

  mkcert -install
  mkcert -key-file ~/.hammoc/key.pem -cert-file ~/.hammoc/cert.pem localhost 127.0.0.1 YOUR_LOCAL_IP
  

  Replace YOUR_LOCAL_IP with your PC's IP address (e.g., 192.168.0.10).

• Install the root CA on your mobile device:

  Find the CA certificate location:

  mkcert -CAROOT
  

  Transfer rootCA.pem to your mobile device, then:

  • Android: Settings → Security → Install certificate
  • iOS: Open the file → Install Profile → Settings → General → About → Certificate Trust Settings → Enable

• Start Hammoc — it will automatically detect the certificates and start in HTTPS mode:

  Hammoc Server running on:
    Local:   https://localhost:3000
    Network: https://192.168.0.10:3000
    TLS:     enabled (certs from ~/.hammoc/)
  

• Open on mobile: Navigate to https://YOUR_LOCAL_IP:3000 and install the PWA.

Option 2: Reverse Proxy

If you already have a reverse proxy (Nginx, Caddy, etc.) handling HTTPS, simply keep Hammoc running in HTTP mode (no certificates needed) and point your proxy to http://localhost:3000.

Environment Variables

Variable	Default	Description
PORT	3000	Server port
HOST	0.0.0.0	Bind address
NODE_ENV	—	Set to production for optimized mode
TRUST_PROXY	false	Enable reverse proxy support (Cloudflare Tunnel, nginx, etc.)
CORS_ORIGIN	true	CORS origin (true allows any; set a URL to restrict)
RATE_LIMIT	200	Max requests per minute per IP
CHAT_TIMEOUT_MS	300000	Chat response timeout (ms)
LOG_LEVEL	INFO/DEBUG	ERROR, WARN, INFO, DEBUG, VERBOSE
TERMINAL_ENABLED	true	Enable/disable terminal feature
TELEGRAM_BOT_TOKEN	—	Telegram bot token for notifications
TELEGRAM_CHAT_ID	—	Telegram chat ID for notifications

License

AGPL-3.0 — See LICENSE for details.

Acknowledgments

• Claude Code by Anthropic — The AI coding assistant that powers Hammoc
• BMAD-METHOD by BMad Code — The agile AI-driven development methodology integrated into Hammoc