Skip to main content
Longshot is organized as a TypeScript monorepo with three core packages that work together to enable multi-agent coding orchestration. Each package has a clear, focused responsibility.

​
Package Architecture

@longshot/core

Core types, utilities, and infrastructure

@longshot/orchestrator

Multi-agent orchestration engine

@longshot/sandbox

Sandbox worker harness

​
Package Dependencies

The packages have a clear dependency hierarchy: 
@longshot/core (foundation)
    ↑
    ├── @longshot/orchestrator
    └── @longshot/sandbox
  • @longshot/core has zero external dependencies (only Node.js built-ins)
  • @longshot/orchestrator depends on @longshot/core
  • @longshot/sandbox depends on @longshot/core
  • Neither orchestrator nor sandbox depend on each other

​
Installation

​
Monorepo Setup

Longshot uses pnpm workspaces. Install all dependencies from the root: 
pnpm install

​
Individual Package Development

Build a specific package: 
# Build core package
pnpm --filter @longshot/core build

# Build orchestrator package
pnpm --filter @longshot/orchestrator build

# Build sandbox package
pnpm --filter @longshot/sandbox build
Run tests for a specific package: 
pnpm --filter @longshot/orchestrator test

​
Using Packages in External Projects

All packages are published as ESM modules with TypeScript declarations: 
// Import from @longshot/core
import { Task, Handoff, createLogger, Tracer } from "@longshot/core";

// Import from @longshot/orchestrator
import { createOrchestrator, Planner, MergeQueue } from "@longshot/orchestrator";

// Import from @longshot/sandbox
import { runWorker, buildHandoff } from "@longshot/sandbox";

​
Package Exports

​
@longshot/core

{
  "name": "@longshot/core",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}
Exports:
  • Core domain types: Task, Handoff, HarnessConfig, MetricsSnapshot, SandboxStatus, LLMEndpoint, LogEntry
  • Structured logging: createLogger, Logger, setLogLevel, getLogLevel
  • Distributed tracing: Tracer, Span
  • Git utilities: createBranch, checkoutBranch, mergeBranch, rebaseBranch, getDiffStat, getRecentCommits, getFileTree, hasUncommittedChanges

​
@longshot/orchestrator

{
  "name": "@longshot/orchestrator",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}
Dependencies:
  • @longshot/core: Core types and utilities
  • @mariozechner/pi-coding-agent: Pi coding agent integration
  • dotenv: Environment variable management
Exports:
  • Configuration: OrchestratorConfig
  • Core components: createOrchestrator, Planner, Subplanner, WorkerPool, MergeQueue, TaskQueue, Reconciler, Monitor
  • LLM client: LLMClient
  • Utilities: ScopeTracker, ConcurrencyLimiter, GitMutex

​
@longshot/sandbox

{
  "name": "@longshot/sandbox",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}
Dependencies:
  • @longshot/core: Core types and utilities
  • @mariozechner/pi-coding-agent: Pi coding agent integration
Exports:
  • Worker harness: runWorker
  • Handoff utilities: buildHandoff, getGitDiffStat

​
Development Workflow

​
Building All Packages

# Build all packages in dependency order
pnpm build

# Watch mode for development
pnpm dev

​
Type Checking

# Check all packages
pnpm typecheck

# Check specific package
pnpm --filter @longshot/orchestrator typecheck

​
Linting and Formatting

# Lint all code
pnpm lint

# Format all code
pnpm format

# Check formatting without changes
pnpm format:check

​
Cleaning Build Artifacts

# Clean all packages
pnpm clean

# Clean specific package
pnpm --filter @longshot/core clean

​
Package Managers

Longshot requires pnpm 9.0.0 or higher: 
{
  "packageManager": "[email protected]"
}
This ensures consistent dependency resolution and workspace linking across all development environments.

​
Next Steps

Core Package

Explore types, logging, and git utilities

Orchestrator Package

Learn about task planning and worker management

Sandbox Package

Understand the worker harness contract

Build docs developers (and LLMs) love

Get started for freeTalk to us