---

Opinionated Claude Code agents, skills, and commands for autonomous software development integrating Claude's agentic features with Linear MCP + Git Worktrees.

Quick Start

CLI (Available Now):

git clone git@github.com:justinhe16/claude-surf.git
cd claude-surf
claude

/check-surf      # check what's missing
/prep-surf       # install missing prerequisites
/global-surf     # install agents + skills globally

Desktop App:

Visual dashboard for managing worktrees - download latest release

Installation

Desktop App

1. Download the latest release for your platform:

   • macOS: Download Claude-Surf-x.x.x-arm64-mac.zip (Apple Silicon) or -x64-mac.zip (Intel)
   • Windows: Download Claude-Surf-Setup-x.x.x.exe
   • Linux: Download Claude-Surf-x.x.x.AppImage or .deb

2. Install:

   macOS:

   # Extract the zip file (double-click or use unzip)
   
   # IMPORTANT: Remove quarantine attribute (required for unsigned apps)
   xattr -cr ~/Downloads/"Claude Surf.app"
   
   # Move to Applications folder
   mv ~/Downloads/"Claude Surf.app" /Applications/
   
   # Open the app
   open /Applications/"Claude Surf.app"

   Windows:

   • Run the .exe installer
   • Follow the installation wizard

   Linux (AppImage):

   chmod +x Claude-Surf-*.AppImage
   ./Claude-Surf-*.AppImage

   Linux (Debian/Ubuntu):

   sudo dpkg -i claude-surf-app_*.deb

Note: The macOS app is currently unsigned. macOS will block it unless you remove the quarantine attribute with the xattr command shown above.

Usage

Skill	Description
/check-surf	Check if gh, Linear MCP server, etc. are installed
/prep-surf	Install missing prerequisites (gh, Linear MCP server, etc.)
/global-surf	Copy all agents and skills to ~/.claude/ for global use
/solo-surf <branch> [terminal]	Create git worktree + open new terminal with Claude
/robot-surf <ticket-id>	Autonomous: Linear ticket → planned implementation → PR with code review
/robot-surf-prompt "task"	Autonomous: Freeform task → planned implementation → PR with code review

---

Agents & Skills

Agents

Agents are specialized AI assistants that Claude can delegate work to. When you are under a /solo-surf, you can use any of these specific agents to help your work.

Agent	What it does
orchestrator	Coordinates multi-step tasks, spawns other agents, manages iteration loops
staff-engineer-planner	Assesses task complexity, decides if planning is needed, surfaces architectural risks
software-engineer	Implements features, runs tests, creates PRs, monitors CI, fixes failures
code-reviewer	Reviews PRs for bugs, security issues, code quality; approves or requests changes

Skills

Skills are slash commands that teach Claude how to do specific workflows.

Skill	What it does
check-surf	Checks for git, gh CLI, Linear MCP server, terminal apps
prep-surf	Installs gh via Homebrew, configures Linear MCP server, handles auth
global-surf	Copies agents + skills to ~/.claude/ for use in any project
solo-surf	Creates git worktree, copies .env files, opens terminal with Claude
robot-surf	Full automation: fetch Linear ticket → assess complexity → plan (if needed) → implement → PR → CI → code review → done
robot-surf-prompt	Full automation from freeform prompt: assess complexity → plan (if needed) → implement → PR → CI → code review → done

The Robot-Surf Loop

/robot-surf ENG-123  or  /robot-surf-prompt "task description"
       │
       ▼
┌──────────────────────────────────────────────┐
│  1. Fetch Linear ticket (or use prompt)      │
│  2. Create git worktree + branch             │
│  3. staff-engineer-planner assesses          │
│     ├─ SIMPLE → skip to step 5               │
│     └─ COMPLEX → continue to step 4          │
│  4. Plan agent creates implementation plan   │
│  5. software-engineer implements (with plan) │
│  6. Create PR, wait for CI green             │
│  7. code-reviewer reviews                    │
│  8. If issues → back to step 5               │
│  9. Repeat until approved (max 3x)           │
│ 10. Report: "PR ready for review"            │
└──────────────────────────────────────────────┘

---

Customization

Agents live in .claude/agents/ (project) or ~/.claude/agents/ (global).

---
name: my-agent
description: When to use this agent
tools: Read, Edit, Write, Bash
model: sonnet
---

Your system prompt here...

---

Structure

claude-surf/
├── .claude/
│   ├── agents/           # AI agents for delegated work
│   │   ├── orchestrator.md
│   │   ├── staff-engineer-planner.md
│   │   ├── software-engineer.md
│   │   └── code-reviewer.md
│   └── skills/           # Slash commands
│       ├── check-surf/
│       ├── prep-surf/
│       ├── global-surf/
│       ├── solo-surf/
│       ├── robot-surf/
│       └── robot-surf-prompt/
├── app/                  # Electron desktop app (WIP)
│   ├── src/
│   │   ├── main/         # Main process
│   │   ├── renderer/     # UI
│   │   └── shared/       # Shared code
│   └── package.json
└── README.md

Deployment and Releases

Creating a Release

1. Test locally

   cd app
   npm run dev     # Test the app works
   npm run build   # (Optional) Test the build works locally

2. Commit your changes

   git add .
   git commit -m "Your changes"
   git push

3. Create and push a tag

   git tag v1.0.0
   git push origin v1.0.0

4. GitHub Actions builds automatically

   • Builds for macOS, Windows, and Linux
   • Creates GitHub Release
   • Uploads installers (.dmg, .exe, .AppImage, .zip)
   • Monitor progress at: https://github.com/justinhe16/claude-surf/actions

5. (Optional) Write release notes

   • Go to https://github.com/justinhe16/claude-surf/releases
   • Edit the release and add notes about what's new

Build Outputs

The GitHub Actions workflow produces:

• macOS: .dmg installer and .zip
• Windows: .exe installer and .zip
• Linux: .AppImage and .deb package

License

MIT

Author

Justin He