writ-ai-coding-assistant

---

Table of Contents

• Overview
• Demo
• Features
• Tech Stack
• Architecture
  • Monorepo Structure
  • Data Flow
• Getting Started
  • Try It Instantly
  • Local Development
• CLI Usage
  • Modes
  • Slash Commands
  • File Mentions
• Supported AI Models
• Environment Variables
• Authentication & Security
• Rate Limits & Portfolio Quota
• Deployment
• Roadmap
• Contributing
• License
• Author
• Acknowledgments

---

Overview

Writ is a full-stack, terminal-native AI coding assistant — conceptually similar to tools like OpenCode or Claude Code — built as a personal portfolio project to explore agentic tool-calling, real-time streaming UIs in the terminal, and end-to-end type-safe full-stack TypeScript.

It ships as two cooperating pieces:

• A CLI (packages/cli) — a React-powered Terminal UI (TUI) that runs locally on your machine, renders the chat interface, and executes filesystem/shell tool calls on your own machine.
• A server (packages/server) — a Hono API that handles authentication, LLM inference across multiple providers, session persistence, billing, and rate limiting.

The CLI never talks to LLM providers directly — every request is authenticated, metered, and proxied through the server, which keeps API keys, database credentials, and billing logic entirely off the client.

---

Demo

---

Features

• Agentic tool use — the assistant can read, write, and surgically edit files, search the codebase with grep/glob, list directories, and run shell commands, all executed locally in your project's working directory.
• Two operating modes
  • Plan — read-only exploration and analysis (no file writes, no shell access).
  • Build — full read/write access, including the bash tool, for actually implementing changes.
• Multi-provider model routing — switch between Google Gemini, Groq, Mistral, Cerebras, and NVIDIA NIM models from a single /models picker, with per-model provider options (reasoning effort, thinking budgets, parallel tool calls) tuned individually.
• Streaming, resumable sessions — chat history is persisted server-side per session, survives reconnects, and supports interrupting/regenerating responses mid-stream.
• @-mention file references — type @ to fuzzy-search and reference files/directories from your project directly in a prompt, with path-traversal protection baked in.
• Slash command palette — fast keyboard-driven access to sessions, models, modes, themes, auth, and billing (see Slash Commands).
• Secure browser-based login — OAuth 2.0 Authorization Code + PKCE flow via Clerk; the CLI never holds a client secret.
• Usage-based billing — integrated with Polar.sh for compute-credit checkout, a self-serve billing portal, and metered token consumption across providers normalized into a single internal unit ("Writ Tokens").
• Theming — multiple built-in color themes, persisted to disk per user.
• Production observability — Sentry error tracking, performance tracing, and profiling on the server.
• Abuse-resistant public demo — a rolling 7-day message quota protects the hosted demo from runaway usage (see Rate Limits).

---

Tech Stack

Layer	Technology
CLI runtime	Bun
Terminal UI	@opentui/react — a Zig-native terminal renderer with a React reconciler
CLI routing	react-router (in-memory router for screen navigation)
Server framework	Hono on Node.js
AI orchestration	Vercel AI SDK (ai, @ai-sdk/react)
LLM providers	Google Gemini, Groq, Mistral, Cerebras, NVIDIA NIM (via OpenAI-compatible adapter)
Database	PostgreSQL (Neon, serverless)
ORM	Prisma (v7) with the @prisma/adapter-pg driver adapter
Auth	Clerk — OAuth 2.0 Authorization Code + PKCE
Billing	Polar.sh — checkout, customer portal, usage metering
Validation	Zod
Observability	Sentry (errors, tracing, profiling)
Package manager	pnpm workspaces
Server build	tsup (bundling) / tsx (dev)
CLI build	Bun's native bundler

---

Architecture

Monorepo Structure

writ/
├── packages/
│   ├── cli/              # Terminal UI client (Bun + opentui/react)
│   │   └── src/
│   │       ├── components/    # Chat messages, dialogs, command menu, prompt area
│   │       ├── hooks/          # useAppChat, useCommandMenu
│   │       ├── layouts/        # Root layout, app shell
│   │       ├── lib/             # API client, auth, OAuth, billing, themes, utils
│   │       ├── providers/      # Theme, toast, dialog, input-stack, session context
│   │       ├── screens/        # Home, new-session, session
│   │       └── tools/           # Local tool executors (bash, file ops, search)
│   │
│   ├── server/           # Hono API (deployed to Render.com)
│   │   └── src/
│   │       ├── routes/          # sessions, chat, billing, oauth-callback
│   │       ├── middlewares/    # auth, compute-credit & portfolio-quota gating
│   │       ├── lib/              # Clerk auth, Polar billing, model resolver, system prompt
│   │       └── views/           # Landing page
│   │
│   ├── db/                # Prisma schema, generated client, Neon connection
│   ├── shared/            # Shared Zod schemas, tool contracts, model registry
│   └── assets/             # Logo & favicon
│
├── pnpm-workspace.yaml
├── package.json            # Root workspace scripts
└── .env.example

Data Flow

1. The CLI authenticates the user via a browser-based OAuth + PKCE flow against Clerk, relayed through the server's /auth/callback route, and stores the resulting access token locally at ~/.writ/auth.json (file permissions 0600).
2. A prompt is sent to POST /sessions/:sessionId/chat on the server, authenticated via the Clerk-issued bearer token.
3. The server merges the request with persisted session history, resolves the requested model/provider, and streams a response back via streamText from the AI SDK.
4. If the model requests a tool call (e.g. readFile, bash), the CLI — not the server — executes it locally inside the user's own project directory, then reports the result back into the conversation.
5. On completion, token usage is recorded against the user's Polar.sh meter, and the conversation is persisted to Postgres.

---

Getting Started

Try It Instantly

No cloning required — the CLI is published to npm and runs anywhere Bun is installed:

# Install Bun, if you don't already have it
curl -fsSL https://bun.sh/install | bash

# Run Writ
bunx @keepserene/writ

Note: The hosted demo runs against a shared free-tier deployment with a quota — see that section for details and how to self-host with your own API keys for unlimited use.

Local Development

**Prerequisi