-Puter
03fc32bd6d
Add the complete project-scoped Zopu chat, Signal extraction, and work-routing loop: Backend (signalRouting.ts): - Agent-token-gated functions for the full routing cycle: list evidence, create signal, list signals, list active issues, attach signal to issue, create issue from signal, begin issue, get project context, list projects - attachSignalToIssue requires signal.projectId to exist and equal issue.projectId (org equality alone is insufficient) - createIssueFromSignal is idempotent: queries existing attachments before creating, returns created/reused flag - Duplicate attach retries return existing relation without emitting a duplicate event - All functions deny-by-default with agent token validation Schema: - Add signalIssueAttachments table with indexes by signal, issue, and the composite (signalId, issueId) for idempotent lookups Agent tools (tools/signals.ts): - Nine Flue tool definitions bound to the organization-scoped agent instance ID, calling the agent-gated Convex functions - Organization ID never accepted as free input; always from the bound instance Zopu agent (zopu.ts): - Comprehensive routing-loop instructions: assess actionability, identify project, create signal only when actionable, route via attach or create, explain outcome, optionally begin - Wiring of routing tools into the agent definition Tests (signalRouting.test.ts): - Authentication: invalid token rejected on every function - Project scoping: evidence, signals, issues scoped correctly - Idempotency: duplicate attach, duplicate create-from-signal, duplicate signal creation - Attach vs create: both paths verified - Cross-project rejection: signal and issue must be in same project - Org-scoped signal attach rejected (no projectId) - Provenance: exact raw text preserved through routing loop - Begin issue: transition and auth verification
code
This project was created with 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:
bun install
Convex Setup
This project uses Convex as a backend. You'll need to set up Convex before running the app:
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:
bun run dev
Open 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:
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.jsonandapps/web/components.json
Add more shared components
Run this from the project root to add more primitives to the shared UI package:
npx shadcn@latest add accordion dialog popover sheet table -c packages/ui
Import shared components like this:
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
- 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 modebun run build: Build all applicationsbun run dev:web: Start only the web applicationbun run dev:server: Start the Convex development serverbun run dev:setup: Setup and configure your Convex projectbun run check-types: Check TypeScript types across all appsbun run dev:native: Start the React Native/Expo development serverbun run dev:tui: Start the terminal UIbun run check: Run Vite+ format/lint checks and workspace TypeScript checksbun run lint: Run Vite+ lint checksbun run format: Run Vite+ formattingbun run fix: Apply Ultracite fixesbun run staged: Run Vite+ checks against staged filesbun run hooks:setup: Install Vite+ native Git hooks withvp configbun run dev:desktop: Start the Electrobun desktop app with HMRbun run build:desktop: Build the stable Electrobun desktop appbun run build:desktop:canary: Build the canary Electrobun desktop appbun run dev:daemon: Start the daemon with Bun watch modebun run build:daemon: Compile the daemon binarybun 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-runto inspect the promptbun run subtree list: List configured vendored Git subtreesbun run subtree status [name]: Inspect subtree metadata and local dirtinessbun run subtree preview <name>: Fetch and display upstream commits not yet represented by the subtreebun run subtree update <name> --yes: Safely pull a configured subtree with squash semantics