# code

This project was created with [Better-T-Stack](https://github.com/AmanVarshney01/create-better-t-stack), a modern TypeScript stack that combines React, React Router, Convex, and more.

## Features

- **TypeScript** - For type safety and improved developer experience
- **React Router** - Declarative routing for React
- **React Native** - Build mobile apps using React
- **Expo** - Tools for React Native development
- **TailwindCSS** - Utility-first CSS for rapid UI development
- **Shared UI package** - shadcn/ui primitives live in `packages/ui`
- **Convex** - Reactive backend-as-a-service platform
- **Agent daemon** - Bun/Effect service that leases Convex commands and dispatches them to AgentOS/RivetKit actors
- **Authentication** - Better-Auth
- **Electrobun** - Lightweight desktop shell for web frontends
- **OpenTUI** - Terminal interface in `apps/tui`
- **Oxlint** - Oxlint + Oxfmt (linting & formatting)
- **Vite+** - Unified Vite toolchain, workspace task runner, linting, and formatting

## Getting Started

First, install the dependencies:

```bash
bun install
```

## Convex Setup

This project uses Convex as a backend. You'll need to set up Convex before running the app:

```bash
bun run dev:setup
```

Follow the prompts to create a new Convex project and connect it to your application.

Copy environment variables from `packages/backend/.env.local` to `apps/*/.env`.

Then, run the development server:

```bash
bun run dev
```

Open [http://localhost:5173](http://localhost:5173) in your browser to see the web application. Use the Expo Go app to run the mobile application. Your app will connect to the Convex cloud backend automatically.

### Daemon setup

The daemon is a separate Bun process that connects to Convex, claims queued `daemonCommands`, and runs AgentOS actor actions. Copy `apps/daemon/.env.example` to `apps/daemon/.env`, replace the placeholder `CONVEX_URL`, then run:

```bash
bun run dev:daemon
```

Build the compiled daemon binary with `bun run build:daemon`; the output is `apps/daemon/dist/code-daemon`.

## UI Customization

React web apps in this stack share shadcn/ui primitives through `packages/ui`.

- Change design tokens and global styles in `packages/ui/src/styles/globals.css`
- Update shared primitives in `packages/ui/src/components/*`
- Adjust shadcn aliases or style config in `packages/ui/components.json` and `apps/web/components.json`

### Add more shared components

Run this from the project root to add more primitives to the shared UI package:

```bash
npx shadcn@latest add accordion dialog popover sheet table -c packages/ui
```

Import shared components like this:

```tsx
import { Button } from "@code/ui/components/button";
```

### Add app-specific blocks

If you want to add app-specific blocks instead of shared primitives, run the shadcn CLI from `apps/web`.

## Git Hooks and Formatting

- Optional native Vite+ hooks: `bun run hooks:setup`
- Docs: [Vite+ commit hooks](https://viteplus.dev/guide/commit-hooks)
- Run checks: `bun run check`

## Project Structure

```
code/
├── apps/
│   ├── web/         # Web application (React + React Router)
│   ├── native/      # Mobile application (React Native, Expo)
│   ├── desktop/     # Electrobun shell around the web build
│   ├── tui/         # OpenTUI terminal client
│   ├── daemon/      # Bun/Effect daemon for AgentOS command execution
├── packages/
│   ├── backend/     # Convex backend functions and schema
│   ├── primitives/  # Shared Effect services, including AgentOS helpers
│   ├── env/         # Runtime environment validation
│   ├── ui/          # Shared shadcn/ui components and styles
├── repos/           # Vendored upstream references; excluded from normal tooling
```

## Available Scripts

- `bun run dev`: Start all applications in development mode
- `bun run build`: Build all applications
- `bun run dev:web`: Start only the web application
- `bun run dev:server`: Start the Convex development server
- `bun run dev:setup`: Setup and configure your Convex project
- `bun run check-types`: Check TypeScript types across all apps
- `bun run dev:native`: Start the React Native/Expo development server
- `bun run dev:tui`: Start the terminal UI
- `bun run check`: Run Vite+ format/lint checks and workspace TypeScript checks
- `bun run lint`: Run Vite+ lint checks
- `bun run format`: Run Vite+ formatting
- `bun run fix`: Apply Ultracite fixes
- `bun run staged`: Run Vite+ checks against staged files
- `bun run hooks:setup`: Install Vite+ native Git hooks with `vp config`
- `bun run dev:desktop`: Start the Electrobun desktop app with HMR
- `bun run build:desktop`: Build the stable Electrobun desktop app
- `bun run build:desktop:canary`: Build the canary Electrobun desktop app
- `bun run dev:daemon`: Start the daemon with Bun watch mode
- `bun run build:daemon`: Compile the daemon binary
- `bun run docs:update [commit-or-range]`: Ask a detected coding-agent CLI to update first-party documentation for a commit or revision range; use `--dry-run` to inspect the prompt
- `bun run subtree list`: List configured vendored Git subtrees
- `bun run subtree status [name]`: Inspect subtree metadata and local dirtiness
- `bun run subtree preview <name>`: Fetch and display upstream commits not yet represented by the subtree
- `bun run subtree update <name> --yes`: Safely pull a configured subtree with squash semantics