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 (Longshot will run git init if needed)
  • Claude Code CLI — Longshot spawns claude as a subprocess. Install it from @anthropic-ai/claude-code

2. Start Longshot

Navigate to your project directory and run:

cd your-project
longshot

On first run, Longshot initializes the project — scaffolding a .longshot/ directory with your project spec, task index, and history. These files are auto-committed to git.

Longshot then connects to the cloud proxy and prints the URL to open on your phone:

Connected to proxy
Open on your phone: https://app.longshothq.com/app/your-daemon-id/tasks

If this is your first time, Longshot will walk you through logging in — it opens a browser for authentication and saves the token automatically.

Local-only mode

If you don't want to use the cloud proxy, use the --local flag to start a local web server instead:

longshot --local

Open http://localhost:3333 on any device on the same network. To use a different port:

longshot --local --port 8080

3. 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 researches your codebase — reads files, understands your architecture, finds relevant patterns — then writes a structured spec with scope, approach, and acceptance criteria. You don’t write the spec; the agent does.

Review the spec on the Tasks tab. You can:

  • Refine — chat with the agent to adjust scope, approach, or criteria
  • Mark Ready — approve the spec and queue it for implementation

Once marked ready, the agent implements against the agreed spec — not a vague prompt.

4. 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

5. 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
  • Verify — run tests, take screenshots, or custom checks before deciding

Next steps

  • Daemon setup — details on managing multiple machines, tokens, and troubleshooting
  • API Reference — explore the full API for programmatic access
  • FAQ — common questions about security, data, and billing