# Local Project Mode

`chaser dev` is Chaser's local-first workflow for development. Keep your editor, local files, and local Git workflow on your machine, while shell commands and agents run inside a remote sandbox.

This mode is designed for the case where your local checkout is the source of truth and the sandbox is the execution mirror.

## When to use it

Use `chaser dev` when:

- You already have a project checked out locally.
- You want to keep editing files with your existing editor and local tooling.
- You want builds, installs, tests, and agent work to happen in an isolated remote sandbox.
- You want sandbox-originated file changes to sync back locally with a ledger and rollback path.

Use [Remote Workspace Development](/docs/guides/remote-workspace-development) instead when the remote workspace itself should be the canonical copy of the project.

## Quickstart

From a project directory:

```bash
chaser login
cd ~/code/my-project
chaser dev
```

`chaser dev`:

- resolves the project scope from the Git root when one exists, otherwise from the current directory
- preserves the nested launch directory as the remote working directory under `/workspace`
- creates or reuses a project-scoped sandbox workspace by default
- falls back to an ephemeral sandbox when persistent workspaces are unavailable
- syncs the local project into the sandbox before attaching a shell

When you reconnect later, Chaser reuses the same project-scoped workspace when possible so remote caches and toolchains survive across shell sessions.

## How it works

Local Project Mode is sync-based, not a shared filesystem mount.

The local project stays authoritative. Chaser keeps a mirrored copy in the sandbox and reconciles changes in both directions with a short polling loop.

```text
Local project (authoritative)
    |
    |  bootstrap + incremental sync
    v
Sandbox /workspace (execution mirror)
```

This model keeps local editors and Git workflows unchanged while still running code in a remote microVM.

## What syncs

Bootstrap and incremental sync reuse your local ignore rules and add Chaser-specific defaults:

- `.gitignore` is respected during local scanning
- `.chaserignore` adds project-specific exclusions for Local Project Mode
- `.chaser/` is always local-only metadata
- heavy generated directories such as `node_modules`, `target`, `.venv`, `.next`, `.turbo`, and similar remain remote-only by default

Git metadata is treated specially:

- the local Git state is authoritative
- Git metadata is pushed from local to remote for read-oriented tooling
- remote `.git` mutations do not sync back to the local checkout

This means remote `git status` can stay useful for inspection, while Chaser avoids silently rewriting local Git history.

## Metadata, ledger, and rollback

Each project gets a local metadata directory:

```text
.chaser/
  state.json
  ledger.ndjson
  objects/
  conflicts/
```

Key files:

- `state.json` tracks the current project-mode session, workspace, sync base, and paused conflicts
- `ledger.ndjson` records sandbox-originated mutations applied locally
- `objects/` stores preimages used for rollback
- `conflicts/` stores remote copies for paths that need manual resolution

Useful commands:

```bash
chaser dev status
chaser dev log
chaser dev undo <tx_id>
chaser dev doctor
```

If you omit `<tx_id>`, `chaser dev undo` targets the most recent reversible sandbox-originated transaction.

## Conflict handling

When the same path changes locally and remotely since the last synced base, Chaser does not overwrite your local file.

Instead it:

- leaves the local file in place
- stores the remote version under `.chaser/conflicts/<tx_id>/...`
- records the conflict in the ledger
- pauses syncing for that path until you resolve it locally

Once you edit the local file to the version you want to keep, Chaser treats the local result as the resolution and syncs it back to the sandbox.

## Commands

```bash
# Start project mode from the current project
chaser dev

# Explicit shell form
chaser dev shell

# Force a disposable remote sandbox
chaser dev shell --ephemeral

# Inspect state and health
chaser dev status
chaser dev doctor

# Review and undo remote-applied edits
chaser dev log
chaser dev undo tx_...
```

## Compatibility shim

`chaser-sh` remains available as a compatibility path for tools that insist on driving a shell via the `SHELL` environment variable.

Example:

```bash
export SHELL=/usr/local/bin/chaser-sh
```

The recommended surface is still `chaser dev shell`. The shim exists so shell-oriented tools can route through the same project-mode engine when needed.

## Free vs paid behavior

- Paid accounts default to a persistent project-scoped workspace for `chaser dev`
- Free accounts fall back to ephemeral sandbox sessions when persistent workspace creation is unavailable
- Your local files and `.chaser` ledger stay safe on the local machine either way
- The main difference is whether remote caches and long-lived workspace state persist between runs

## Choosing the right surface

| Surface | Best for |
|--------|----------|
| `chaser dev` | Local-first development where the local checkout stays authoritative |
| `chaser shell` / SSH | Remote-first work where the workspace itself is canonical |
| Workspaces import | Repo-first remote environments bootstrapped from GitHub |
| MCP / SDKs / REST | Automation, agents, and infrastructure integration |

## Related

- [Quickstart](/docs/overview/quickstart) -- fastest path to your first `chaser dev` session
- [CLI Reference](/docs/developer-tools/cli-reference) -- full command syntax
- [Remote Workspace Development](/docs/guides/remote-workspace-development) -- remote-first workflow
- [Sandbox Sessions](/docs/sessions/sandbox-sessions) -- sandbox lifecycle and exec details