https://github.com/arach/contextual
Hangar-themed UI for context engineering on pi.dev sessions — three-pane workshop (threads / conversation / context rack), session-forest tree, built on HudsonKit.
https://github.com/arach/contextual
Last synced: 14 days ago
JSON representation
Hangar-themed UI for context engineering on pi.dev sessions — three-pane workshop (threads / conversation / context rack), session-forest tree, built on HudsonKit.
- Host: GitHub
- URL: https://github.com/arach/contextual
- Owner: arach
- Created: 2026-05-11T02:59:45.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-30T21:25:39.000Z (21 days ago)
- Last Synced: 2026-05-30T23:14:18.182Z (20 days ago)
- Language: TypeScript
- Size: 397 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-pi-coding-agent - arach-contextual - themed UI for context engineering on pi.dev sessions — three-pane workshop (threads / conversation / context rack), session-forest tree, built on HudsonKit. | ⭐1 | 10d ago | (Themes)
README
# Contextual
A deliberately *designed* context environment for agentic engineering. Decouples conversation threads from LLM context management: every dispatch is composed fresh from a Fixed zone (pinned-every-call modules) and a Soft zone (recent turns + summaries). Statelessness is a feature.
## Backends
Contextual is vendor-neutral. Two backends ship today:
- **pi-coding-agent** — spawns the `pi` CLI (`@earendil-works/pi-coding-agent`) per dispatch. Native session tree, fork, and on-disk workspace materialization. Pick this when you want pi's rich session ergonomics.
- **pi-ai** — in-process via `@earendil-works/pi-ai`. Stateless; every call rebuilds the full Context from Contextual's Fixed/Soft state. Multiple providers (Anthropic, OpenAI, Google, Mistral, Bedrock). Pick this when you want pure context control.
Toggle per-thread via the backend chip in the top bar.
## Setup
Install dependencies (bun is required):
```bash
bun install
```
For the **pi-coding-agent** backend, install pi globally:
```bash
npm install -g @earendil-works/pi-coding-agent
pi login # OAuth or API key, your choice
```
For the **pi-ai** backend, you'll need an `ANTHROPIC_API_KEY` (or the corresponding key for whichever provider you select). Storage is handled by the `secret` CLI on this machine — never in a `.env` file:
```bash
secret set ANTHROPIC_API_KEY # prompts for the value
```
## Run
Start the dev server with the credential injected into the child env:
```bash
secret run ANTHROPIC_API_KEY -- bun dev
```
For pi-coding-agent only:
```bash
bun dev
```
Open `http://localhost:5173`.
## Architecture
- `src/lib/backends/types.ts` — Backend interface, DispatchRequest, DispatchResult
- `src/lib/backends/pi-coding-agent.ts` — pi CLI backend (subprocess, native sessions)
- `src/lib/backends/pi-ai.ts` — pi-ai backend (in-process, stateless)
- `src/lib/backends/client.ts` — browser-side fetch client
- `vite-plugin-backends.ts` — dev-server router that dispatches to the right backend
Contextual owns the canonical branch/tree manifest. pi-coding-agent dispatches mirror to native pi sessions at `~/.contextual/sessions/`; pi-ai dispatches are stateless and have no on-disk footprint.
See `docs/CTX-001-pi-ai-backend.md` for the design rationale.