NightCode

A terminal-based AI coding agent.

Plan, chat, and build inside your local project with a Bun-powered CLI, Hono API, Prisma ORM, Clerk auth, and AI SDK streaming.

Tutorial

Each chapter has a matching branch so you can check out the code at any point in the tutorial:

git checkout 07-tool-calling  # example: jump to tool calling

Features

• Terminal AI Chat - Run an AI coding assistant directly in your terminal with an OpenTUI and React interface
• Plan and Build Modes - Use read-only planning tools or enable write, edit, and shell execution tools for implementation
• Streaming Responses - Stream model output through the AI SDK with persisted session history
• Local Project Tools - Read files, list directories, glob, grep, write files, edit files, and run shell commands inside the current project
• Multi-Model Support - Use supported Anthropic and OpenAI chat models from a shared model registry
• Persistent Sessions - Store authenticated user sessions and messages in Postgres via Prisma
• Clerk OAuth - Authenticate the CLI through a browser-based Clerk OAuth flow
• Usage Billing - Meter AI usage as credits through Polar before allowing session and chat actions

Getting Started

Prerequisites

• Bun installed
• PostgreSQL database, such as Neon
• Clerk application configured for OAuth
• Anthropic and/or OpenAI API key
• Polar account and credits meter

1. Clone and install

git clone git@github.com:code-with-antonio/nightcode.git
cd nightcode
bun install

2. Configure environment

cp .env.example .env

Fill in the required values:

API_URL=http://localhost:3000
DATABASE_URL=

ANTHROPIC_API_KEY=
OPENAI_API_KEY=

CLERK_FRONTEND_API=
CLERK_OAUTH_CLIENT_SECRET=
CLERK_OAUTH_CLIENT_ID=
CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
JWT_SECRET=jwt-secret

POLAR_ACCESS_TOKEN=
POLAR_PRODUCT_ID=
POLAR_SERVER=sandbox
POLAR_CREDITS_METER_ID=

3. Set up Clerk OAuth

NightCode authenticates the CLI through a browser-based Clerk OAuth flow. The CLI opens Clerk authorization in the browser, Clerk redirects to the server at /auth/callback, and the server forwards the authorization code back to the local CLI callback server.

In your Clerk dashboard:

1. Go to Configure > Developers > OAuth applications.
2. Click Add OAuth application.
3. Name it anything, for example NightCode.
4. Select these four scopes: openid, email, profile, and offline_access.
5. Turn on Public. This is required for the Authorization Code with PKCE flow used by the CLI.
6. Turn on Consent screen so users can approve the requested scopes.
7. Add http://localhost:3000/auth/callback as a redirect URI for local development.
8. Add your deployed callback URL as another redirect URI for production, for example https://your-deployment.com/auth/callback.

You can keep both local and production redirect URIs on the same OAuth application.

Copy the generated application credentials into .env:

4. Set up Polar billing

NightCode uses Polar credits to gate new work and bill completed AI usage. The server checks the user's active meter balance before creating sessions or sending chat requests, then ingests usage events after AI responses finish.

In your Polar dashboard, use sandbox mode for local development and create a meter with these exact settings:

The event name and metadata key must match exactly. The server sends usage events like this:

{
  name: "nightcode_usage",
  metadata: { credits }
}

Next, create a meter credits benefit and attach it to a one-time purchase product:

1. Create a benefit using the nightcode_credits meter.
2. Set the credited units, for example 1000 credits.
3. Create a one-time purchase product, for example $20 for 1000 credits.
4. Attach the credits benefit to that product.
5. Set the customer portal visibility to private so purchases happen through API-generated checkout links.

Then copy the required Polar values into .env:

The CLI upgrade flow calls /billing/checkout, which opens a Polar checkout URL. The usage flow calls /billing/portal, which opens the customer's Polar portal.

5. Set up the database

Generate the Prisma client:

bun run --cwd packages/database db:generate

Apply your Prisma schema to the configured Postgres database using your preferred Prisma workflow.

6. Run the server

bun run dev:server

The API runs on http://localhost:3000.

7. Run the CLI

In another terminal:

bun run dev:cli

To build and link the local CLI binary:

bun run link:cli
nightcode

Project Structure

packages/
├── cli/                         # OpenTUI + React terminal client
│   ├── bin/                     # nightcode executable shim
│   └── src/
│       ├── components/          # Terminal UI components, dialogs, messages
│       ├── hooks/               # Chat and UI hooks
│       ├── layouts/             # Root terminal layouts
│       ├── lib/                 # API client, auth, OAuth, local tool execution
│       ├── providers/           # Dialog, keyboard, prompt, theme, toast providers
│       └── screens/             # Home, new session, and session screens
├── database/                    # Prisma schema, generated client, database exports
├── server/                      # Hono API for auth, billing, sessions, and chat
└── shared/                      # Shared schemas, tool contracts, and model registry

Scripts

Packages