# Shard

Shard is an experimental, local-first coding-agent harness. A daemon supervises isolated agent processes while browser and SDK clients attach to the same live sessions.

The central idea is detachability: an agent keeps running when a client disconnects, and another client can reattach later without losing the append-only conversation history.

> [!WARNING]
> Shard is under active development. Protocols, configuration, and storage formats may change before a stable release. Review permission prompts and remote deployment settings before using it on important systems.

## Highlights

- Detached agent processes supervised by `shardd`
- Web, headless `shard agent`, and in-process SDK clients
- Multi-client session attachment and permission handling
- Append-only JSONL sessions with deterministic compaction and recall
- OpenAI-compatible provider support, including local compatible endpoints
- Extensible tools, modes, skills, permission rules, and agent definitions
- Tree-sitter-backed code indexing

## Requirements

- [Bun](https://bun.sh/) 1.3 or newer
- Git
- An OpenAI-compatible model endpoint (cloud or local)

## Get started

```sh
git clone <repository-url>
cd shard
bun install --frozen-lockfile
```

`bun install` builds a development bundle at `dist/shard` (via the `prepare`
script); it still expects Bun and `node_modules`. For deployment, build a native,
self-contained executable plus its required web/grammar assets:

```sh
bun run build:release
# release/shard/ contains shard, build/, and tree-sitter/*.wasm
```

This produces a platform-specific Bun native executable (Linux/macOS and CPU
architecture must be built separately). Users do not need Bun, Node, or the source
tree; distribute the generated archive. The browser UI and Tree-sitter grammars are
runtime data, so the release is intentionally a small directory rather than literally
one file. Run `bun run build:native` when only the CLI/daemon binary is needed.

For development, run `./dist/shard` directly, or `bun link` to put `shard` on your `PATH`. 

Create your first provider config with the interactive wizard:

```sh
./dist/shard setup
# Or configure, then launch the browser experience in one command:
./dist/shard setup --web
```

The wizard walks you through choosing a provider (OpenAI, Ollama, or a custom
OpenAI-compatible endpoint), a model alias, and — for bearer-auth providers — the
environment variable that holds your API key. The key itself is never written to the
config file. Pass `--yes` to accept defaults non-interactively (expert skip); an existing
config is never overwritten (use `--force`).

The generated config is stored at `~/.config/shard/config.json` (or under
`XDG_CONFIG_HOME`). Set the environment variable named by the selected provider
configuration, then inspect the resolved, redacted configuration:

```sh
export OPENAI_API_KEY='...'
./dist/shard config show
```

Start the web client:

```sh
./dist/shard            # daemon + loopback web client (prints the URL); default
./dist/shard web        # same — daemon + browser client
./dist/shard daemon     # daemon only (unix-socket)
```

A bare `shard` (or `shard web`) starts the daemon and its loopback web listener, then prints the URL to stdout. Use `shard agent` for a headless stdio server speaking the per-agent protocol.

The daemon prints its local connection details at startup. It binds to loopback by default. See [WEB-DEPLOYMENT.md](WEB-DEPLOYMENT.md) before exposing it through a network or reverse proxy.

The web client is a SvelteKit SPA compiled into a gitignored `build/` directory. On a fresh checkout the daemon builds it automatically on first start (`shardd: web build missing — building with vite (one time)…`); you can also build it explicitly with `bun run web:build`. See [DEVELOPMENT.md](DEVELOPMENT.md) for the automatic-build details and the `SHARD_SKIP_WEB_BUILD` opt-out.

## Development

```sh
bun run dev          # watch the CLI entrypoint
bun run web:dev      # web development server
bun run check        # lint, types, tests, and production builds
```

Useful individual checks:

```sh
bun run lint
bun run typecheck
bun run test:ci
bun run test:web
bun run web:build
bun run build:cli
bun run build
```

`test:ci` runs the Bun suite with an isolated home directory so it cannot touch a developer's real Shard state.

For a detailed walkthrough of configuring providers and models, setting up the web environment, and adding color themes, see [DEVELOPMENT.md](DEVELOPMENT.md).

## Project structure

```text
src/contracts/   Wire-safe interfaces and schemas
src/core/        Agent loop, tools, permissions, sessions, compaction
src/daemon/      Process supervision, registry, proxy, web server
src/protocol/    Shared command and event protocol
src/sdk/         In-process client
src/web/         Browser client components and state
src/routes/      SvelteKit routes
tests/           Unit, integration, and end-to-end tests
```

For deeper context, read:

- [DEVELOPMENT.md](DEVELOPMENT.md) — detailed setup guide: providers/models, web environment, themes
- [PRODUCT.md](PRODUCT.md) — product goals and constraints
- [ARCHITECTURE.md](ARCHITECTURE.md) — process model and dependency boundaries
- [PROTOCOL.md](PROTOCOL.md) — transport-neutral wire protocol
- [src/web/DESIGN.md](src/web/DESIGN.md) — web interface design record
- [WEB-DEPLOYMENT.md](WEB-DEPLOYMENT.md) — remote deployment and security

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security-sensitive reports should follow [SECURITY.md](SECURITY.md).

## License

Licensed under the [Apache License 2.0](LICENSE.md).