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.

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 1.3 or newer
• Git
• An OpenAI-compatible model endpoint (cloud or local)

Get started #

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:

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:

./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:

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

Start the web client:

./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 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 for the automatic-build details and the SHARD_SKIP_WEB_BUILD opt-out.

Development #

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:

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.

Project structure #

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 — detailed setup guide: providers/models, web environment, themes
• PRODUCT.md — product goals and constraints
• ARCHITECTURE.md — process model and dependency boundaries
• PROTOCOL.md — transport-neutral wire protocol
• src/web/DESIGN.md — web interface design record
• WEB-DEPLOYMENT.md — remote deployment and security

Contributing #

See CONTRIBUTING.md. Security-sensitive reports should follow SECURITY.md.

License #

Licensed under the Apache License 2.0.