# devist
[](https://github.com/WebchemistCorp/devist/actions/workflows/ci.yml)
[](LICENSE)
Project bootstrap CLI for AI-assisted development.
A Rust CLI that lets you scaffold new projects from templates, run multiple
project backends without overloading your machine, and stay on top of what's
in your codebase — even when most of the code was written by AI.
Built by [Webchemist](https://github.com/WebchemistCorp).
> **Status:** v0.1.0 beta. APIs and template manifest schema may change
> before v1.0.
## Why
Two pains modern dev workflows hit hard:
1. **Backend stack overload.** One Supabase or Postgres docker stack per
project melts your laptop. devist runs at most one backend at a time —
switching projects auto-stops the previous one.
2. **AI-assisted code blindness.** When AI writes most of the code, you stop
knowing how the system fits together. devist gives you `brief`, `scan`,
`explain`, and `watch` to keep your mental model intact.
## Install
### From source (any platform)
```bash
git clone https://github.com/WebchemistCorp/devist
cd devist
cargo install --path .
```
### One-liner (macOS / Linux, prebuilt binary)
```bash
### Specific version
```bash
### Manual binary download
Grab the archive for your platform from the
[Releases page](https://github.com/WebchemistCorp/devist/releases) and
extract `devist` somewhere on your `PATH`.
> Homebrew tap (`brew install WebchemistCorp/devist/devist`) and crates.io
> publish are planned for v1.0.
## Quick Start
```bash
devist setup
devist template add https://github.com/WebchemistCorp/devist-templates
devist init my-app --template=react-supabase
devist start my-app --dev
```
## Command Reference
### Project lifecycle
| `devist setup` | Initialize `~/.devist/` workspace |
| `devist doctor` | Check required CLIs (git, docker, node, pnpm, supabase) |
| `devist init <name> --template=<t>` | Create a new project |
| `devist init <name> -t <t> --var key=value` | Override template variables |
| `devist start <name>` | Start the project's backend (lazy: stops others) |
| `devist start <name> --dev` | Backend + dev server |
| `devist stop [name]` | Stop active backend (or specific one) |
| `devist project list` | List registered projects (active marked) |
| `devist project forget <name>` | Remove from registry (files untouched) |
### Templates
| `devist template list` | List installed templates |
| `devist template add <git-url>` | Clone a template repo |
| `devist template sync` | `git pull` all templates |
| `devist template remove <name>` | Delete a template directory |
### Worker (background observer)
A long-running daemon watches a parent folder of projects, records every
file event into a local SQLite store (L1), pushes batches to your Supabase
project (L2), and — when configured — generates AI advice via the `claude`
CLI with long-term semantic memory in mem0.
| `devist worker start` | Start the daemon (prompts for monitor folder on first run) |
| `devist worker stop` | Stop the daemon |
| `devist worker status` | Show PID, monitor folder, event/sync counts |
| `devist worker watch` | Tail recent events live in the terminal |
| `devist worker advice [--project N]` | List recent advice rows |
| `devist worker memory search <query>` | Semantic search across mem0 |
| `devist worker rules show\|path\|init [--project N]` | Manage `rules.md` |
| `devist worker config show\|get\|set\|path` | Manage worker config |
State lives in `~/.devist/worker/`:
```
worker.db SQLite event log (L1 store)
config.toml Worker config
rules.md Global rules (injected into Claude prompt)
worker.pid Daemon PID
worker.log Daemon stdout/stderr
```
#### Supabase L2 setup
Apply the migration once on your Supabase project:
```
psql "$SUPABASE_DB_URL" -f migrations/0001_worker_events.sql
# or paste the file into the Supabase SQL editor
```
Then point the worker at it:
```
devist worker config set supabase_url https://xxxx.supabase.co
devist worker config set supabase_key <service-role-key>
devist worker config set client_id $(hostname) # idempotency key
devist worker stop && devist worker start
```
The daemon batch-flushes pending events every `sync_interval_secs` (30s default).
Re-pushes are idempotent on `(client_id, client_event_id)`.
#### Rules
Two layers, both optional plain markdown:
```
~/.devist/worker/rules.md # global
<monitor>/<project>/.devist/rules.md # project (overrides)
```
Both are concatenated into the advice prompt verbatim. Use them to set tone,
focus areas, and what should/shouldn't be persisted to mem0.
#### Advice rate limits (config keys)
| `advice_enabled` | `true` | Master kill switch |
| `advice_idle_seconds` | `60` | Quiet window after burst before processing |
| `advice_min_batch` | `3` | Skip burst smaller than this |
| `advice_max_per_hour` | `6` | Per project, sliding 1h window |
| `mem0_max_writes_per_hour` | `20` | Global, sliding 1h window |
| `mem0_confidence_threshold` | `0.7` | Min Claude confidence to persist a fact |
## Layout
```
~/.devist/
├── config.toml Your settings
├── registry.toml Projects you've created
├── state.toml Currently active backend
├── templates/ Cloned template repos
├── worker/ Background worker state (db, pid, log, config)
└── cache/ Reserved
```
## Templates
A template is a directory with a `devist.toml` manifest plus any project files.
Files ending in `.tmpl` get variable substitution; everything else is copied
as-is (binary-safe).
Minimal `devist.toml`:
```toml
[meta]
name = "my-stack"
version = "0.1.0"
description = "Short description"
author = "You"
tags = ["fullstack"]
[variables]
project_name = { default = "{{folder_name}}" }
description = { default = "A new project" }
[stack]
type = "supabase" # or "docker-compose", "none"
[commands]
install = "pnpm install"
dev = "pnpm dev"
backend_start = "supabase start"
backend_stop = "supabase stop"
test = "pnpm test"
```
Variables are substituted in `*.tmpl` files with `{{ name }}` syntax.
Auto-provided: `project_name`, `folder_name`. Override with `--var key=value`.
A single git repo can host multiple templates as subdirectories. The official
`WebchemistCorp/devist-templates` repo is structured this way.
## Development
```bash
cargo build
cargo test
cargo run -- --help
```
Required: Rust 1.70+, git. For most templates: docker, node, pnpm, supabase
CLI.
## Status
Active development. Phases:
| 0.1 | Phase 1 | Core CLI, react-supabase + wordpress |
| 0.2 | Phase 2 | + fastapi-postgres, react-native-supabase |
| 0.3 | Phase 3 | + flutter-supabase, nestjs-postgres, rust-axum |
| 0.4 | Phase 4 | + brief, scan, explain, watch |
| 1.0 | Phase 5 | Public release (Homebrew, crates.io) |
Currently at end of Phase 4.
## License
MIT