# Devist
[](https://github.com/WebchemistCorp/devist/actions/workflows/ci.yml)
[](LICENSE)
Project bootstrap CLI for AI-assisted development. **Powered by Reso** —
a memory system that quietly learns your craft and aligns AI advice with
your patterns over time.
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).
## Reso — the memory that thinks for itself
Most "AI memory" tools are write-once buckets that grow into noise. **Reso** is
different: a memory store designed to **prune itself, audit its own outputs,
and stay aligned with your decisions** — without you babysitting it.
Every observation, decision, and preference accumulates in Reso, classified by:
- **scope** — `project` (specific decisions), `tech` (stack patterns), `user` (your style)
- **priority** — `constraint` (always enforced) → `strong` → `preference` → `info`
- **source** — `user` (your hand) vs `claude` (extracted) — user-authored entries are protected
- **tech tags** — auto-detected from `package.json`, `Cargo.toml`, etc.
Over time, AI advice in any new project starts **in tune with your past** —
no cold start, no repetition of resolved issues, no contradictions of your
explicit decisions. Subtle. Persistent. Yours.
> Backed by Supabase (canonical, with daily snapshots) + mem0 (semantic index,
> replaceable). Lose mem0, keep your memory.
### The self-maintaining daemon
Devist's worker daemon doesn't just write to Reso — it **continuously refines**
both the memory store and the advice inbox in the background:
| **`advice`** | 5s poll, fires on file-change burst idle (60s) | Asks Claude for facts + actionable advice, writes to inbox + Reso |
| **`verify`** | 20s tick, 8/h cap per project | Checks open advice against current file content — auto-acks the ones you fixed |
| **`audit`** | 30min OR 5+ pending | Re-evaluates the inbox against the same MUST/MUST NOT bar — auto-acks the noise |
| **`consolidate`** | 1h OR 10+ new memories | Reviews the entire Reso store — keep / update / merge / delete with safety rails |
| **`jobs`** | 5s poll | Handles dashboard-initiated jobs (apply advice, generate rules) |
| **main loop** | 5s poll, 30s sync | Watches files, syncs to Supabase, sends heartbeats |
**Safety rails everywhere**:
- All deletions are `soft-delete` — restorable via SQL.
- `source='user'` rows are never auto-deleted or demoted.
- `priority='constraint'` rows are never auto-demoted.
- Hourly Claude-call budget per loop keeps cost bounded (~30 calls/hour total).
- Every action is attributed (`acked_by='verify' | 'audit' | 'apply' | 'user'`).
This is what "a memory system that learns your craft" actually requires — not
just storage, but a **sleep cycle**. Reso has one.
> **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
### Homebrew (macOS / Linux)
```bash
brew install WebchemistCorp/devist/devist
```
### crates.io (any platform with Rust toolchain)
```bash
cargo install devist
```
### From source
```bash
git clone https://github.com/WebchemistCorp/devist
cd devist
cargo install --path .
```
### 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`.
### macOS: "확인되지 않은 개발자" / "unidentified developer" warning
Devist binaries shipped via Homebrew or the GitHub Releases page are
**not yet code-signed with an Apple Developer ID** (paid program — on
the roadmap). macOS Gatekeeper will block them on first launch with an
"unidentified developer" dialog.
Two ways around it:
```bash
# Option 1 — strip the quarantine attribute (one-shot)
xattr -d com.apple.quarantine "$(which devist)"
```
```bash
# Option 2 — first-launch override
# Right-click the binary in Finder → "Open" → "Open anyway"
```
This warning does **not** appear when you install via `cargo install`
(builds locally) or `cargo install --path .` (builds from source).
## 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