8cd479f20c
- Commit the vendored Flue SKILL.md under .agents/skills/flue and the .claude/skills/flue symlink plus skills-lock.json entry. - Rewrite AGENTS.md down to the repo's actual conventions and expand README.md with daemon/TUI/dev script notes.
135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
# 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
|