npm package: @lucid-agent/cli
Description: An open-source AI agent that watches your code, thinks while you're away, and remembers everything across sessions.
Latest version: 0.2.0

<p align="center">
  <img src="assets/lucid-logo.svg" width="80" />
</p>

<h1 align="center">Lucid</h1>
<p align="center">
  <em>Your codebase never sleeps.</em>
</p>
<p align="center">
  An open-source AI agent that watches your code, thinks while you're away,<br/>
  and remembers everything across sessions.
</p>

<p align="center">
  <a href="https://lucid.engineering">Website</a> &bull;
  <a href="#quick-start">Quick Start</a> &bull;
  <a href="#what-is-lucid">What is Lucid?</a> &bull;
  <a href="#how-it-works">How It Works</a> &bull;
  <a href="#supported-models">Supported Models</a> &bull;
  <a href="#architecture">Architecture</a>
</p>

---

## Quick Start

```bash
npm install -g @lucid-agent/cli
cd your-project
lucid init
```

That's it. Lucid will scan your project, build an initial memory, and run its first analysis in under two minutes.

## What is Lucid?

Most AI coding tools forget everything between sessions. You spend the first ten minutes of every conversation re-explaining your project, your conventions, your ongoing work. Lucid fixes this.

Lucid runs as a lightweight background daemon that **watches** your codebase for meaningful changes, **thinks** about them using the model of your choice, and **remembers** what it learns in a persistent, growing memory. It catches bugs you missed, spots patterns across commits, and delivers insights to your desktop, Slack, or Discord — only when they matter.

Lucid brings always-on background intelligence to every developer — with any model provider, fully open source.

## How It Works

```
                    ┌─────────────────────────────────┐
                    │          LUCID DAEMON            │
                    │                                  │
  File changes ───▶ │  WATCH ──▶ TICK ──▶ DREAM      │
  Git events   ───▶ │           (cheap)   (thorough)  │
                    │                        │         │
                    │                   ┌────┴────┐    │
                    │                   │ MEMORY  │    │
                    │                   │ 3-Layer │    │
                    │                   └────┬────┘    │
                    │                        │         │
                    │                     NOTIFY ─────▶│──▶ Desktop / Slack / Discord
                    └─────────────────────────────────┘
```

1. **Watch** — Monitors file system events and git hooks. Debounces noise.
2. **Tick** — A cheap, fast model call (~$0.0001) decides: "Is this worth waking up for?"
3. **Dream** — If yes, a thorough analysis runs: code review, issue detection, memory consolidation.
4. **Remember** — Findings persist in a 3-layer memory system that grows smarter over time.
5. **Notify** — Actionable insights delivered through your preferred channel.

The key insight: **cheap ticks, expensive dreams.** Background monitoring costs nearly nothing. Real analysis only happens when it matters.

## Features (Phase 1 — Shipping Now)

- **Always-on daemon** — Runs in the background, checking for changes every 60 seconds
- **Persistent memory** — LUCID.md index survives across sessions, grows with your project
- **Budget controls** — Daily spend caps, per-dream cost tracking, transparent pricing
- **Desktop notifications** — Native alerts for high-priority insights
- **Git-aware** — Understands branches, commits, merges, and conflicts
- **First-run magic** — Install to first insight in under 2 minutes
- **Memory search** — `lucid recall` to search across all logs and memory

### New in v0.2

- **Multi-model** — OpenAI (GPT-4o), Google (Gemini), and local models via Ollama
- **Full 3-layer memory** — Topic files + SQLite archive with FTS5 full-text search
- **Slack & Discord** — Webhook notifications with priority-based routing
- **Cross-layer consolidation** — Automatic deduplication, contradiction resolution, pruning

### Coming Soon

- **Lucid Cloud** — Hosted daemon, GitHub App, team memory (Phase 4)

## CLI Commands

```bash
# Setup
lucid init                        # Interactive setup in your repo
lucid init --provider anthropic   # Non-interactive with provider flag

# Daemon
lucid start                       # Start the background daemon
lucid start --foreground          # Run in foreground (for debugging)
lucid stop                        # Stop the daemon
lucid status                      # Show daemon state and memory stats

# Analysis
lucid dream                       # Force a dream cycle now
lucid dream --focus "auth,api"    # Dream with specific focus areas

# Memory
lucid recall "authentication"     # Search memory for a topic
lucid recall --recent             # Show recent insights
lucid memory                      # Show the current LUCID.md index
lucid memory --stats              # Memory size, topic count, etc.

# Activity
lucid log                         # Show today's activity
lucid log --yesterday             # Yesterday's activity
lucid log --week                  # This week's summary

# Configuration
lucid config                      # Show current config
lucid config set models.dream "openai:gpt-4o"
```

## Configuration

Create a `lucid.toml` in your project root (generated by `lucid init`):

```toml
[models]
tick = "anthropic:claude-haiku"      # Cheap and fast for tick checks
dream = "anthropic:claude-sonnet"    # Thorough for dream analysis
max_daily_spend = 5.00               # Hard budget cap in USD

[daemon]
tick_interval_seconds = 60           # How often to check for changes
consolidate_every = 5                # Consolidate memory every N dreams

[notifications]
desktop = true                       # Native desktop notifications
# [notifications.slack]
# webhook_url = "https://hooks.slack.com/services/..."
# min_priority = "medium"            # low, medium, high, critical
# [notifications.discord]
# webhook_url = "https://discord.com/api/webhooks/..."
# min_priority = "medium"

[watch]
ignore = [
  "node_modules/**",
  "dist/**",
  ".lucid/**",
  "*.lock",
]
```

API keys are read from environment variables (never stored in config):

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...
# Ollama: no key needed, just run `ollama serve`
```

## Supported Models

| Provider | Tick Model | Dream Model | Status |
|----------|-----------|-------------|--------|
| Anthropic | Claude Haiku | Claude Sonnet | **Available** |
| OpenAI | GPT-4o Mini | GPT-4o | **Available** |
| Google | Gemini Flash | Gemini Pro | **Available** |
| Ollama | Any local model | Any local model | **Available** |

## Architecture

Lucid uses a **3-layer memory system** inspired by how production-grade agent architectures manage context:

**Layer 1: LUCID.md** — A lightweight markdown index at your project root. Always loaded, always current. Under 4KB. Contains pointers to deeper knowledge.

**Layer 2: Topic Files** — Focused deep-dives stored in `.lucid/topics/`. Created and pruned by the dream engine. Loaded only when relevant.

**Layer 3: Session Archive** — Full dream transcripts in SQLite with full-text search. Never loaded into model context directly — queried when historical context is needed.

The **tick evaluator** is the critical cost-control mechanism. On every interval, it makes a tiny model call (<600 tokens total) to decide if a full dream is warranted. This keeps background costs under $2/day while ensuring nothing important is missed.

## The Memory File

`LUCID.md` lives at your project root and is the shared knowledge your team's AI has about the codebase:

```markdown
# Lucid Memory Index

## Project
- TypeScript monorepo, Next.js frontend + Express API, PostgreSQL
- Auth: NextAuth with Google OAuth, session-based
- Deploy: Vercel (frontend) + Railway (API)

## Active Concerns
- [topic:auth-migration] Migrating from session to JWT — in progress
- [topic:perf-issues] API response times degraded after analytics middleware

## Patterns Observed
- Team tends to skip error handling in API routes — flag in reviews
- Database queries in /api/users are N+1 — suggested fix on 2026-03-28

## Recent Dreams
- 2026-03-31 02:14 — Reviewed feat/jwt-auth, found token expiry not handled
- 2026-03-30 18:30 — Consolidated memory, pruned 3 stale topics
```

`LUCID.md` is committed to your repo — it's shared project knowledge. The `.lucid/` directory (logs, topics, database) is gitignored.

## Roadmap

### Phase 1: Core MVP (Complete)

- [x] CLI skeleton — 9 commands (init, start, stop, status, dream, log, recall, memory, config)
- [x] Background daemon — detached process, PID management, Unix socket IPC, graceful shutdown
- [x] File watcher — chokidar-based with debouncing and configurable ignore patterns
- [x] Git hooks — post-commit, post-checkout, post-merge event capture
- [x] Tick evaluator — cheap model call (<600 tokens) to gate expensive dreams
- [x] Dream engine — full code analysis with budget gating and insight validation
- [x] Layer 1 memory — LUCID.md with section-aware merge, 4KB enforcement, mtime caching
- [x] Anthropic provider — Claude Haiku (tick) + Claude Sonnet (dream) with retry + backoff
- [x] Desktop notifications — node-notifier integration
- [x] Daily activity log — append-only markdown logs with dream summaries
- [x] Cost tracking — per-dream cost estimation, daily budget cap
- [x] Configuration — TOML config with env var overrides, Zod validation
- [x] Landing page — single `index.html`, spec-compliant design, CSS terminal animation
- [x] Text-based `recall` — search across LUCID.md + log history

### Phase 2: Memory & Multi-Model (Complete)

- [x] OpenAI provider (GPT-4o-mini tick, GPT-4o dream)
- [x] Google provider (Gemini Flash tick, Gemini Pro dream)
- [x] Ollama provider (local models, zero API cost)
- [x] Layer 2 topic files — `.lucid/topics/` with on-demand loading
- [x] Layer 3 session archive — SQLite + FTS5 full-text search
- [x] Memory consolidation — contradiction resolution, deduplication, pruning

### Phase 3: Integrations (Complete)

- [x] Slack notifications (webhook-based with Block Kit formatting)
- [x] Discord notifications (webhook-based with embeds)
- [x] Priority-based notification routing (configurable per channel)

### Phase 4: Lucid Cloud (Future)

- [ ] Semantic `recall` — embedding-based memory search
- [ ] GitHub App for webhook integration
- [ ] Hosted daemon infrastructure
- [ ] Web dashboard for memory browsing
- [ ] Team memory — shared insights across developers
- [ ] Waitlist → beta invites flow

## Development

```bash
git clone https://github.com/jnoble157/lucid.git
cd lucid
npm install
npm run build
npm run test
```

See [AGENTS.md](AGENTS.md) for architecture decisions, coding standards, and file-specific guidance.

See [docs/STATUS.md](docs/STATUS.md) for detailed implementation status and what's needed for each phase.

## Contributing

Contributions welcome! Here's how:

1. Fork the repo and create a branch (`feat/my-feature` or `fix/my-bug`)
2. Follow the coding standards in [AGENTS.md](AGENTS.md) — strict TypeScript, no `any`, max 300 lines per file
3. Add tests for new functionality
4. Run `npm run build && npm test` before submitting
5. Open a PR with a clear description

Priority areas for contribution:
- **Semantic recall** — embedding-based memory search (needs `EmbeddingProvider` design)
- **GitHub webhooks** (`src/notify/github-webhook.ts`) — cloud version foundation
- **Integration tests** — CLI commands, daemon socket, git hooks

## Support

If Lucid is useful to you, consider supporting development:

<a href="https://buymeacoffee.com/joshnoble"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?style=flat-square&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>

## License

[MIT](LICENSE)

---

<p align="center">
  <sub>Inspired by dreams.</sub>
</p>