gent

Minimal, opinionated agent harness — built on Effect.

Philosophy

• Minimal: small surface area, codebase understandable in an afternoon
• Opinionated: one way to do things, no configuration bloat
• Effect-native end-to-end: services, layers, schema, streams — no Promise edges in the public surface

Quick Start

bun install
bun run gate # typecheck + lint + fmt + build + test

Run the TUI

bun run --cwd apps/tui dev # default mode
bun run --cwd apps/tui dev -p "..."# one-shot prompt → session view
bun run --cwd apps/tui dev -H "..."# headless: stream to stdout, exit
bun run --cwd apps/tui dev -c # continue last session for cwd
bun run --cwd apps/tui dev sessions # list sessions

Run the standalone server

bun run --cwd apps/server dev

gent defaults to a server-per-DB topology: one server owns the SQLite store and accepts multiple clients. The TUI binary embeds a server by default; a standalone apps/server is only needed for remote topologies.

Architecture

TUI / SDK / HTTP client
│
▼
transport contract
│
┌──────┴──────┐
▼ ▼
direct RPC / HTTP
adapter adapter
│
▼
app services (commands / queries / events)
│
▼
runtime + platform boundaries

See ARCHITECTURE.md for the full noun model (Server, Profile, SessionRuntime, Tool/Request/Action, Resource, Reaction).

Layout

apps/
├── tui/ OpenTUI client over the shared transport contract
└── server/ HTTP + RPC adapter
packages/
├── core/ domain, storage, providers, runtime, server, extensions/api, test-utils
├── extensions/ all 27 builtin extensions (imports only @gent/core/extensions/api)
├── sdk/ direct + RPC transports over one client contract
├── tooling/ custom oxlint rules, fixtures, build/test diagnostics
└── e2e/ PTY/transport/supervisor end-to-end tests

@gent/core uses subpath exports — no barrels. Import from specific files (@gent/core/domain/event, @gent/core/runtime/agent/agent-loop.actor, etc.).

Configuration

Data lives under ~/.gent/:

• data.db — SQLite database (sessions, branches, events, interactions, tasks)
• auth.json — auth keys (KeyValueStore-backed)
• plans/ — plan files

Testing

bun run test# ~2-4s product behavior tests
bun run test:diagnose # print slowest test chunks without failing on duration
bun run test:e2e # ~60-120s PTY + supervisor + worker-http
bun run gate # full pre-commit gate

bun:test directly (not vitest) — bun:sqlite requires the Bun runtime.

Contributing

See CONTRIBUTING.md for code style, Effect patterns, and test conventions.

License

MIT