Mobile-first web interface for CoStrict AI agents

---

English | 中文

---

What is CoStrict?

CoStrict is a terminal-based AI coding assistant that lets you collaborate with large language models to complete coding tasks without leaving the command line. It provides:

• Multiple launch modes — TUI interactive interface (cs), non-interactive mode (cs run "...") for scripts and automation, and web interface (cs web)
• Powerful built-in tools — file read/write, shell execution, code search, network requests, and more
• Extensible via plugins — custom tools and MCP servers for unlimited expansion
• Flexible configuration — manage model selection, tool permissions, themes, and shortcuts via costrict.json
• IDE integration — deep integration with Zed, JetBrains, Neovim via ACP protocol, and VS Code extension support

What is CoStrict Manager?

CoStrict Manager is a modern AI agent management platform built specifically for CoStrict. It provides a mobile-first web interface so you can manage, control, and code with CoStrict AI agents from any device — including your phone or tablet.

CoStrict Manager acts as a web UI layer on top of CoStrict CLI, connecting to the CoStrict server (port 5551) and exposing a full-featured management interface through a backend API (port 5003).

Tech Stack

Backend

• Runtime: Bun - High-performance JavaScript runtime
• Framework: Hono - Lightweight, ultrafast web framework
• Database: Better SQLite3
• Validation: Zod
• Auth: Better Auth

Frontend

• Framework: React 19 + TypeScript
• Build Tool: Vite 7
• UI Components: Radix UI + Tailwind CSS
• State Management: React Query (@tanstack/react-query) + Zustand
• Forms: React Hook Form + Zod
• Code Editor: Monaco Editor
• Markdown: React Markdown + Mermaid

Monorepo Architecture

• Package Manager: pnpm (Workspace)
• Project Structure:
  • backend/ - Backend API service
  • frontend/ - Frontend web application
  • packages/ - Shared packages
  • shared/ - Shared type definitions

Quick Start

Prerequisites

• Node.js >= 18
• pnpm >= 10.28.1
• Bun >= 1.0
• CoStrict CLI installed and running

Docker Deployment (Recommended)

# Clone repository
git clone https://github.com/y574444354/costrict-manager.git
cd costrict-manager

# Copy environment config
cp .env.example .env

# Start services
docker-compose up -d

# Access the application
# Open http://localhost:5003

On first launch, you'll be prompted to create an admin account.

Local Development

# Install dependencies
pnpm install

# Copy environment config
cp .env.example .env

# Start development servers (frontend + backend)
pnpm dev

# Or start separately
pnpm dev:backend   # Backend: http://localhost:5003
pnpm dev:frontend  # Frontend: http://localhost:5173

Project Structure

costrict-manager/
├── backend/              # Backend service
│   ├── src/             # Source code
│   └── tests/           # Test files
├── frontend/            # Frontend application
│   ├── src/            # Source code
│   │   ├── components/ # React components
│   │   ├── pages/      # Pages
│   │   ├── hooks/      # Custom hooks
│   │   └── lib/        # Utilities
│   └── public/         # Static assets
├── packages/            # Monorepo packages
│   └── memory/         # Memory management module
├── shared/             # Shared type definitions
├── scripts/            # Build and deployment scripts
└── docs/               # Documentation

Development Guide

Common Commands

# Development
pnpm dev              # Start frontend & backend dev servers
pnpm dev:backend      # Start backend only
pnpm dev:frontend     # Start frontend only

# Build
pnpm build            # Build all modules
pnpm build:backend    # Build backend
pnpm build:frontend   # Build frontend

# Testing
pnpm test             # Run backend tests
cd backend && bun test <filename>  # Run single test file
cd backend && vitest --ui          # Test UI interface
cd backend && vitest --coverage    # Coverage report (80% threshold)

# Code Quality
pnpm lint             # Lint frontend & backend
pnpm lint:backend     # Lint backend only
pnpm lint:frontend    # Lint frontend only
pnpm typecheck        # TypeScript type checking

# Docker
pnpm docker:build     # Build Docker image
pnpm docker:up        # Start containers
pnpm docker:down      # Stop containers
pnpm docker:logs      # View logs

Code Standards

• No Comments: Self-documenting code only
• No console.log: Use Bun's logger or proper error handling
• Strict TypeScript: Proper typing required everywhere
• Named Imports: Use named imports only, e.g., import { Hono } from 'hono'
• DRY Principle: Don't repeat yourself
• SOLID Principles: Follow object-oriented design principles
• YAGNI Principle: Don't keep code you don't need

Backend Standards

• Use Hono framework with Zod validation and Better SQLite3
• Error handling with try/catch and structured logging
• Follow existing route/service/utility structure
• Use async/await consistently, avoid .then() chains
• Test coverage requirement: minimum 80%

Frontend Standards

• Use @/ alias for imports: import { Button } from '@/components/ui/button'
• UI Components: Radix UI + Tailwind CSS
• Form handling: React Hook Form + Zod
• State management: React Query
• Use React hooks properly, no direct state mutations

Features

Core Features

• Git — Multi-repo support, SSH authentication, worktrees, unified diffs with line numbers, PR creation
• Files — Directory browser with tree view, syntax highlighting, create/rename/delete, ZIP download
• Chat — Real-time streaming (SSE), slash commands, @file mentions, Plan/Build modes, Mermaid diagrams
• Audio — Text-to-speech (browser + OpenAI-compatible), speech-to-text
• AI — Model selection, provider config, OAuth for Anthropic/GitHub Copilot, custom agents with system prompts
• MCP — Local and remote MCP server support with pre-built templates
• Memory — Persistent project knowledge with semantic search and compaction awareness

Mobile Optimization

• Responsive UI design
• PWA installable
• iOS optimized (keyboard handling, swipe navigation)
• Mobile-friendly interface

Configuration

Environment Variables

# Required for production
AUTH_SECRET=your-secure-random-secret  # Generate with: openssl rand -base64 32

# Pre-configured admin (optional)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-secure-password

# For LAN/remote access
AUTH_TRUSTED_ORIGINS=http://localhost:5003,https://yourdomain.com
AUTH_SECURE_COOKIES=false  # Set to true when using HTTPS

# Service ports (default config)
BACKEND_PORT=5003    # Backend API port
FRONTEND_PORT=5173   # Frontend dev server port

Docker Configuration

The project includes complete Docker support:

• Dockerfile - Multi-stage build image
• docker-compose.yml - Container orchestration
• .dockerignore - Build exclusion config

Screenshots

Chat (Mobile)

File Browser (Mobile)

Inline Diff View

Contributing

Contributions are welcome! Please check CONTRIBUTING.md for details.

License

MIT License

---

Links

• CoStrict Official: https://costrict.ai
• CoStrict Docs: https://docs.costrict.ai
• Report Issues: GitHub Issues

---

Made with ❤️ by the CoStrict Team