Getting Started

Get from zero to directing an AI coding agent from your phone in under five minutes.

1. Install the CLI

Install with a single command — no Node.js or npm required:

curl -fsSL https://longshothq.com/install.sh | sh

This downloads a self-contained binary and adds it to your PATH.

Verify the installation:

longshot --version
Alternative: install via npm

If you prefer npm, you can install globally (requires Node.js 18+):

npm install -g @longshot/cli

Or run directly with npx:

npx @longshot/cli

Prerequisites

  • Git — your project must be a git repository
  • Claude Code CLI — Longshot spawns claude as a subprocess. Install it from @anthropic-ai/claude-code

2. Initialize your project

Navigate to your project directory and run:

cd your-project
longshot

On first run, Longshot detects it's a new project and starts interactive onboarding:

  • Single project — scaffolds a .longshot/ directory in the current folder
  • Multi-project — lets you pick subdirectories to manage as separate projects

Longshot creates a .longshot/ directory containing your project spec, task index, and history. If you're in a git repo, these files are auto-committed.

3. Open the mobile UI

After initialization, Longshot starts a local web server:

longshot
# Longshot running at http://localhost:3333

Open this URL on your phone (when on the same network) or in any browser. The UI is mobile-first — designed for thumbs.

To use a different port:

longshot --port 8080

4. Create your first task

From the Chat tab, describe what you want to build:

"Add a user registration form with email and password fields"

Tap Draft Task. The agent creates a task spec — a structured description of the work with scope, approach, and acceptance criteria.

Review the spec on the Tasks tab. You can:

  • Refine — chat with the agent to adjust the spec
  • Mark Ready — approve the spec and mark it ready for implementation

5. Start work

Once a task is marked ready, tap Start Work. The agent begins implementing against the task spec. You can:

  • Watch progress in real time on the agent progress page
  • Walk away — work continues in the background
  • Queue up more tasks — they'll be processed one at a time

6. Review and approve

When the agent finishes, you'll see a Review Diff button. The diff page shows:

  • Visual diff of all changes (what was added, removed, modified)
  • Change summary — what the agent did and why
  • Test results and checks the agent ran
  • Acceptance criteria from the task spec

You can:

  • Approve — commits the changes to git
  • Reject — discards the changes entirely
  • Fix — describe what needs changing; the agent makes targeted fixes

Next steps

  • Set up remote access — control your agent from anywhere, not just your local network
  • API Reference — explore the full API for programmatic access
  • FAQ — common questions about security, data, and billing