gravity

KO | EN

gitlite — search

#c #openai #cloud-native #mysql #developer-tools #sql #agents #html #tailwindcss #java

(★ 9)

Gravity — a desktop workspace for AI coding agents

File Explorer

ZIP Download

- - README.md
- settings.toml
- pre-commit
- - checks.yml
  - release.yml
  - secrets.yml
  - tests.yml
  - visual.yml
  - warm-release-cache.yml
- - .env.example
  - .fallowrc.json
  - .gitignore
  - .oxfmtrc.json
  - .oxlintrc.json
  - index.html
  - knip.json
  - package.json
  - playwright.config.ts
  - pnpm-lock.yaml
  - pnpm-workspace.yaml
  - tsconfig.json
  - vite.config.ts
  - vitest.config.ts
- - .oxfmtrc.json
  - .oxlintrc.json
  - index.html
  - package.json
  - pnpm-lock.yaml
  - pnpm-workspace.yaml
  - README.md
  - styles.css
  - tsconfig.app.json
  - tsconfig.json
  - tsconfig.worker.json
  - wrangler.jsonc
  - wrangler.updater-bridge.jsonc
- - Cargo.toml
- - Cargo.toml
- architecture.md
- protocol.md
- public-builds.md
- - README.md
- gravityd.example.toml
- in.mikolajczuk.gravityd.plist
- check-file-length.sh
- check-packaged-notices.py
- dev.sh
- install-gravityd.sh
- notices.py
- prepare-sidecar.sh
- probe-daemon.mjs
- test_notices.py
- verify.sh
- vr-accept.sh
- vr-ci.sh
- - 0322ceec0b8f15aa2d74a6173c07cc8c6f3764b3.txt
  - 11069edd79019f7dafbe3138841cf289209270dd.txt
  - 16fe87b06e802f094b3fbb0894b137bca2b16ef1.txt
  - 2008402b8a1299cf118ea38e02116bfcc72e53c3.txt
  - 261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64.txt
  - 31aa79387f27e730e33d871925e152e35e428031.txt
  - 3f3d9e0024b1921b067d6f7f88deb4a60cbe7a78e76c64e3f1d7fc3b779b9d04.txt
  - 4080281f12fc44a831babb7bb4f531aeb070078b.txt
  - 4ca822a5cb54142a14070f5be388e60497781615.txt
  - 540ae4c81adb5f64a9f61e222b688880da24300e.txt
  - 74323882c4eeb6ce9f75f1f3269d212038f394d2.txt
  - 871afd9d691846de71e0b83812ba9c7ff00bc7b3ad102dedcaa109f2246d52ad.txt
  - 8dada3edaf50dbc082c9a125058f25def75e625a.txt
  - 8f71f43fee3f78649d238238cbde51e6d7055c82.txt
  - 9cf106272ac3b56b0c4c80218e8fc10a664ca5f4.txt
  - a4a2a1ca3b22fe608ea29144452418e4a91f11ca44666a8a91cb72ec0a70f6ee.txt
  - a6a98a84ac3f77aa01837efa8f4ddf70fa8f5b62.txt
  - b08530d59433b3060f4fad8751ac2610c0b0aff3.txt
  - cd496ba72eb37e83a44958358d1f89a8a28cbc15.txt
  - d38093a7a564c64ad15e459f2e0a1f86a443c8b3.txt
  - d54c6e13e9e952dac17d209171df8657e3cae93beaddace4906150cdec8d02e9.txt
  - de9a7e660e173136b351982a34f715af424ff812.txt
  - e68a7ab37c8accca023db5f1505d48e4375d4324.txt
  - f433b1a53f5b830a205fd2df78e2b34974656c7b.txt
  - index.json
- DAEMON_NOTICES.txt
- DESKTOP_NOTICES.txt
- inventory.json
- README.md
.gitignore
.gitleaks.toml
AGENTS.md
Cargo.lock
Cargo.toml
CLAUDE.md
CONTRIBUTING.md
LICENSE
package.json
pnpm-lock.yaml
README.md
SECURITY.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Always-on, multi-bot desktop app with Claude Code as the agent runtime. A Rust
daemon (`gravityd`) runs on a Mac mini; the Tauri desktop client attaches
from any machine. See the [architecture](docs/architecture.md) for the system
design and the [control-plane protocol](docs/protocol.md) for client APIs.

Builds and tests require no Linear, PostHog, or Cloudflare account. Running real
bots requires your own Claude Code installation and authentication; the test
runtime works without it. See [public-build configuration](docs/public-builds.md)
for telemetry, releases, and secret scanning.

## Layout

```
crates/bus/       shared types, SQLite schema, envelope format
crates/gravityd/      daemon: runtime adapters, durable delivery, scheduler,
                  MCP bridge, WebSocket control plane
apps/desktop/     Tauri v2 + React + xterm.js client
docs/             architecture, WS protocol v2, public-build configuration
ops/              launchd plist + example gravityd.toml
scripts/          repository checks (file-length rule)
```

## Build & test

After installing the desktop and marketing dependencies, run `pnpm run verify`
from the repository root for the full verification suite (macOS and Docker
required). See [CONTRIBUTING.md](CONTRIBUTING.md) for setup.

```sh
# Daemon
cargo build --release            # target/release/gravityd
cargo test --workspace           # unit + integration (uses the runtime double)
cargo clippy --workspace --all-targets
cargo fmt --all --check

# Desktop client
cd apps/desktop
pnpm install
pnpm typecheck && pnpm build     # frontend
../../scripts/prepare-sidecar.sh # stage gravityd as the bundled sidecar (once,
                                 # and after daemon changes)
pnpm tauri dev                   # run the app
```

## Code rules & tooling

**No source file may exceed 400 lines.** Split by concern instead of growing a
file: `crates/gravityd/src/db/`, `crates/gravityd/src/ws/` and `apps/desktop/src/app/`
are the reference examples.

```sh
./scripts/check-file-length.sh   # enforces the limit for Rust + CSS
```

TypeScript is covered by oxlint's `max-lines` rule instead, so the limit is
checked in two places for two toolchains.

The desktop client carries the JS/TS toolchain; `pnpm check` runs the whole
gate and is what CI (and a pre-push hook, if you add one) should call:

```sh
cd apps/desktop
pnpm check          # typecheck + format + lint + knip + tests-with-coverage + fallow
```

| Command | Tool | What it enforces |
| --- | --- | --- |
| `pnpm typecheck` | tsc | strict types, no emit |
| `pnpm format:check` / `pnpm format` | [oxfmt](https://oxc.rs) | formatting (`.oxfmtrc.json`) |
| `pnpm lint` / `pnpm lint:fix` | [oxlint](https://oxc.rs) | correctness, suspicious, perf, React/a11y, `max-lines: 400` (`.oxlintrc.json`) |
| `pnpm knip` | [knip](https://knip.dev) | unused files, exports and dependencies (`knip.json`) |
| `pnpm test` / `pnpm test:watch` | [vitest](https://vitest.dev) + jsdom + Testing Library | unit and component tests (`vitest.config.ts`) |
| `pnpm test:coverage` | vitest + v8 | writes `coverage/coverage-final.json` |
| `pnpm fallow` | [fallow](https://fallow.tools) | dead code, duplication, complexity and CRAP thresholds (`fallow.config.json`) |

### Tests and CRAP

`fallow health` scores untested complexity as CRAP (`CC² × (1 − coverage)³ + CC`),
so it only passes with a real coverage report: `fallow.config.json` points
`health.coverage` at `coverage/coverage-final.json`, and `pnpm check` runs
`test:coverage` before `fallow`. Running `pnpm fallow` on its own after changing
code will read a stale report — run `pnpm test:coverage` first.

Components are tested against `FakeDaemon` (`src/test/fakeDaemon.ts`), an
in-memory implementation of the `DaemonApi` interface in `src/protocol/api.ts`.
That interface exists so nothing in the UI depends on the concrete
`DaemonClient`, and so the double needs no type casts. `DaemonClient` itself is
tested against a scripted `WebSocket` (`src/test/fakeWebSocket.ts`).

### Pre-commit hook

`.githooks/pre-commit` runs oxfmt, oxlint and fallow's coverage-independent
checks (`dead-code`, `dupes`) whenever a commit touches
`apps/desktop/`. Enable it once per clone (it is a native git hook — no
dependency, and `core.hooksPath` is relative so it covers every worktree):

```sh
git config core.hooksPath .githooks
```

`fallow health` is deliberately left out of the hook: it needs a fresh coverage
report, and regenerating one on every commit is too slow. `pnpm check` covers it.

The hook inspects the working tree rather than the index, so a partial
staged-hunk commit is checked against the files as they are on disk. Resolve
validation failures before committing.

## Install (end users)

Open the release DMG and drag **Gravity** to Applications. The app bundles
the daemon as a signed sidecar; on first launch a setup wizard either installs
it as a launchd user agent on this Mac (one click, no sudo) or attaches to a
remote daemon with a device token. Headless machines skip the app:
`./gravityd service install` from the release tarball does the same
install, and `service status` / `service restart` / `service uninstall` manage
it.

A daemon already answering on `49777` stops the install: Gravity refuses to
start rather than run a second one against the same state. If something else —
not a daemon — holds `49777`, the app-managed service waits a few seconds, then
serves on a free port instead and the app follows it there. That moves the bot
bus off the allowlisted `http://127.0.0.1:49777/mcp` URL, which a policy-managed
Mac silently drops, so Settings → Connection flags it and the daemon restarts
onto `49777` as soon as it comes free. Set `negotiate_port = false` in
`gravityd.toml` to get a daemon that refuses to start instead.

## Run the whole stack (development)

`scripts/dev.sh` starts a workspace-private daemon and the client against it —
nothing touches `~/.gravity`, so it can run beside the installed production
daemon and beside other checkouts:

```sh
./scripts/dev.sh                     # gravityd + the real Tauri window
./scripts/dev.sh web                 # gravityd + Vite frontend in the browser
GRAVITY_RUNTIME=double ./scripts/dev.sh # deterministic echo runtime, no tokens spent
```

The daemon gets its own home at `.dev/gravityd/` (gitignored) with a generated
`gravityd.toml`. Ports derive from `CONDUCTOR_PORT` when Conductor sets it —
frontend on `CONDUCTOR_PORT`, daemon on `CONDUCTOR_PORT+1`, defaulting to
1420/1421 — so parallel workspaces do not collide. In browser mode the script
prints the `localStorage` snippet that points the page at that daemon; the
Tauri window picks the daemon up from `GRAVITY_HOME`.

Conductor drives the same script from `.conductor/settings.toml`: the **dev**,
**dev-double**, **app** and **test** run scripts, with `setup` installing the
frontend dependencies.

## Run the daemon (development)

```sh
mkdir -p ~/.gravity
cp ops/gravityd.example.toml ~/.gravity/gravityd.toml   # optional; defaults are sane
cargo run -p gravityd                                   # or: gravityd --config <path>
curl http://127.0.0.1:49777/health
```

On first start the daemon generates `~/.gravity/secrets/client.token`
(mode 0600), which the desktop client reads automatically on the same machine.

For a remote client (laptop over Tailscale), do **not** copy the owner token.
Create a device-scoped credential instead — Devices panel in the app, or
`create_device` over the protocol — choose `read` and/or `control` grants,
and enter the one-time token plus the Tailscale host/port in the remote app's
connection settings. Revoking the device immediately prevents reconnection.

### Backup & restore

```sh
gravityd backup                       # ~/.gravity/backups/backup-<timestamp>
gravityd backup --out /path/to/dir
gravityd restore --from /path/to/dir  # refuses if a db exists
gravityd restore --from /path/to/dir --overwrite   # moves current db aside first
```

Backups use SQLite's online backup API and include configuration manifests
(project/bot config files) but never secrets or bot workspaces. Retention
pruning (messages, deliveries, routine runs; FTS index kept in sync) runs
daily by default — see `[retention]` in `gravityd.toml`.

## Mac mini service

```sh
cargo build --release
./target/release/gravityd service install   # binary → ~/.gravity/bin, launchd user agent
sudo pmset -a sleep 0 disablesleep 1    # keep the mini awake
```

`service install` copies the invoked binary to `~/.gravity/bin/gravityd`,
writes `~/.gravity/gravityd.toml` if missing, and bootstraps the
`in.mikolajczuk.gravityd` launchd agent — rerun it after a rebuild to upgrade in
place. `service restart` bounces that agent without touching the install, which
kills every running bot session mid-turn; Settings → Connection offers the same
thing behind a confirmation. `ops/in.mikolajczuk.gravityd.plist` remains for
fully manual setups.

## How it works, briefly

- Each **bot** is a provisioned directory (`~/.gravity/projects/<p>/bots/<b>`)
  with `system.md`, `mcp.json`, and a workspace containing `CLAUDE.md` and
  cooperative `.claude/settings.json` (permission rules + lifecycle hooks that
  report state to the daemon). The runtime adapter spawns `claude` there in a
  PTY; the client renders it with xterm.js, preserving native prompts.
- **Messages** are durable rows before delivery. A worker leases due
  deliveries, posts rendered envelopes (`[msg #42 from BOB · task] …`)
  to the session's inbox socket, retries with backoff, and surfaces terminal
  failures. Bots consume and acknowledge via the `gravity-bus` MCP server
  (`send_message`, `complete_task`, `check_inbox`, …) with per-bot scoped
  tokens.
- **Bot-to-bot sends** create one task + one delivery per message, with hop
  counts and origin chains for loop prevention.
- **Routines** use cron, interval, or named-signal triggers with unique
  occurrences, leases, overlap policies, and catch-up on restart. Bots can
  create and manage their own routines, which are enabled on creation.
- The **WS control plane** (protocol v2) is authenticated, versioned, and
  reconnectable with terminal replay cursors. Multiple clients can watch a bot;
  clients with the `control` grant can type and resize its terminal.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and pull requests.

## License

Gravity is licensed under the [MIT License](LICENSE). Third-party dependencies
retain their respective licenses.

gravity

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README