reflex-agent 0.19.0 → 0.19.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reflex authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,54 +1,75 @@
-# Reflex
+# Reflex — local-first AI agent + knowledge base for your files
 
-Local-first AI knowledge base + agent platform. You point Reflex at a
-directory ("a Space"), and an agent (Claude Code or Codex) becomes
-your second brain for that directory: it keeps a knowledge tree, runs
-scheduled workflows, recalls past conversations, and dispatches
-sub-tasks in isolated git worktrees.
+**Reflex turns any folder into a second brain run by an AI agent.** Point it at
+a directory, and Claude Code or OpenAI Codex maintains a living knowledge base,
+remembers every conversation, runs scheduled workflows in the background, and
+dispatches sub-tasks in isolated git worktrees — all stored as plain markdown on
+your machine. No cloud, no database, no daemon.
 
-Everything is stored as plain markdown + JSON in your filesystem. No
-external database, no cloud, no daemon. The only persistent process is
-the Next.js server itself.
+[![npm](https://img.shields.io/npm/v/reflex-agent.svg)](https://www.npmjs.com/package/reflex-agent)
+![Node](https://img.shields.io/badge/node-%E2%89%A522-3c873a.svg)
+![Next.js](https://img.shields.io/badge/Next.js-15-black.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Install
+```sh
+npm i -g reflex-agent
+reflex start          # opens the web UI at http://localhost:3210
+```
 
-Prerequisites:
+> **Local-first AI assistant · personal knowledge management (PKM) · second
+> brain · autonomous agent platform.** Your notes, chats, and automations live
+> in your filesystem as markdown you can read, grep, and version-control —
+> Reflex just makes an agent fluent in them.
 
-- **Node.js 22+** ([nodejs.org](https://nodejs.org/) or `nvm`/`fnm`).
-  Node 24 recommended (built-in SQLite powers session search).
-- A coding-agent CLI authenticated:
-  - `npm i -g @openai/codex && codex login`, or
-  - `npm i -g @anthropic-ai/claude-code && claude login`
+---
 
-Install Reflex globally:
+## Why Reflex?
 
-```sh
-npm i -g reflex-agent
-# or: pnpm add -g reflex-agent
-```
+A cloud chatbot forgets you between sessions, can't act while you're away, and
+keeps your data on someone else's server. Reflex is built the other way around:
+
+- **Local-first & private.** Everything is markdown + JSON under your control.
+  Network access is opt-in (LLM calls, web fetch, GitHub installs); Reflex
+  browses and reads fully offline.
+- **Persistent memory & recall.** A durable per-project memory plus full-text
+  search over *every* past conversation — the agent never re-asks who you are.
+- **Autonomous by schedule.** Background workflows wake on their own clock
+  (hourly / daily / weekly) and do work without you in the loop.
+- **A platform, not a prompt.** Installable mini-app **utilities** add UI,
+  commands, skills, and automations — and can securely share data with each
+  other through a permissioned, audited grant system.
+- **Bring your own agent.** Runs on **Claude Code** or **OpenAI Codex**, with
+  **MCP** servers as on-demand tools.
 
-Launch the web UI:
+## Quickstart
+
+**Prerequisites**
+
+- **Node.js 22+** ([nodejs.org](https://nodejs.org/) or `nvm`/`fnm`). Node 24
+  recommended — its built-in SQLite powers conversation search.
+- An authenticated coding-agent CLI:
+  - `npm i -g @openai/codex && codex login`, or
+  - `npm i -g @anthropic-ai/claude-code && claude login`
+
+**Install & run**
 
 ```sh
-reflex start              # opens http://localhost:3210 in your browser
+npm i -g reflex-agent          # or: pnpm add -g reflex-agent
+reflex start                   # http://localhost:3210
 reflex start --port 4000 --no-open
 ```
 
-Dev runs on `:3211` by default so a `pnpm dev` and an installed
-`reflex start` can co-exist without a port collision.
-
-## First run
+**First run**
 
-1. Click **Add a root** on the home screen and pick a directory.
-2. On the Space dashboard, the onboarding wizard asks a few short
-   questions to seed memory + suggest a first workflow.
-3. Open a chat — type in plain language. The agent reads / writes the
-   `.reflex/` tree, your memory files, and (with permission) shell +
-   web tools.
+1. Click **Add a root** and pick a directory — that folder becomes a *Space*.
+2. The onboarding wizard seeds memory and suggests a first workflow.
+3. Open a chat and type in plain language. The agent reads/writes the
+   `.reflex/` tree, your memory files, and (with permission) shell + web tools.
 
-## What Reflex actually does
+## Features
 
-### A knowledge base per Space
+### 📚 A knowledge base per Space
 
 The agent builds a tree of markdown notes under `<your-dir>/.reflex/`:
 
@@ -68,57 +89,57 @@ The agent builds a tree of markdown notes under `<your-dir>/.reflex/`:
 
 See [docs/kb.md](docs/kb.md) and [docs/architecture.md](docs/architecture.md).
 
-### Cross-session memory
-
-Eight bounded markdown files capture who the user is and what the
-project is about. Every chat starts with this loaded into the system
-prompt — the agent never re-asks who you are.
-
-A weekly system task rolls up journal entries into a `RECENT.md`
-summary. A hygiene scanner refuses memory writes that look like
-prompt injection, credentials, or invisible unicode.
-
-See [docs/memory.md](docs/memory.md).
+### 🧠 Cross-session memory
 
-### Searchable conversation history
+Eight bounded markdown files capture who you are and what the project is about,
+loaded into every chat's system prompt. A weekly task rolls up the journal into
+a summary; a hygiene scanner refuses writes that look like prompt injection,
+credentials, or invisible unicode. See [docs/memory.md](docs/memory.md).
 
-Every journal entry + chat transcript across every Space is indexed
-into a SQLite FTS5 database under `$REFLEX_HOME/sessions.db`. The
-agent (or you, or a utility) can ask "what did we say about X?" with
-ranked snippets returning in milliseconds.
+### 🔎 Searchable conversation history
 
+Every journal entry and chat transcript across every Space is indexed into a
+SQLite **FTS5** database. Ask *"what did we decide about X?"* and get
+ranked snippets in milliseconds — the substrate for true long-term recall.
 See [docs/sessions.md](docs/sessions.md).
 
-### Linear workflows, scheduled
-
-The user (or the agent) composes "recipes" from typed steps —
-`web-fetch`, `ask-agent`, `kb-write`, `image-generate`, etc. The
-background scheduler fires triggered ones hourly / daily / weekly.
+### ⏰ Scheduled, autonomous workflows
 
+Compose "recipes" from typed steps — `web-fetch`, `ask-agent`, `kb-write`,
+`image-generate`, `notify`, and more. The in-process scheduler fires triggered
+workflows hourly / daily / weekly, so the agent acts while you're away.
 See [docs/workflows.md](docs/workflows.md).
 
-### Installable utilities
-
-Mini-apps that bring a UI iframe, server actions, slash commands,
-skills, system-prompt addenda, and workflows. Shipped curated or
-installed from GitHub. Two examples ship by default:
+### 🧩 Installable utilities + the Share Plane
 
-- **`learn-anything`** — chat-driven topic learning, materialised into
-  the KB.
-- **`task-board`** — Kanban board with agent-dispatch, git worktrees,
-  pre/post hooks, auto-pickup.
+Utilities are mini-apps that bundle a UI iframe, server actions, slash commands,
+skills, system-prompt addenda, and workflows — shipped curated or installed from
+GitHub. They can **share data with each other** through the **Share Plane**: a
+permission-gated, fully-audited grant system where one utility reads another's
+data (`kb.scoped*`) or calls a verb it exports (`capabilities.invoke`), only
+with your **just-in-time consent** — never blanket access. Two utilities ship by
+default:
 
-See [docs/utilities.md](docs/utilities.md).
+- **`learn-anything`** — chat-driven topic learning, materialised into the KB.
+- **`task-board`** — Kanban board with agent-dispatch, git worktrees, pre/post
+  hooks, and auto-pickup.
 
-### Agent dispatch via worktrees
+See [docs/utilities.md](docs/utilities.md) and [docs/sharing.md](docs/sharing.md).
 
-Code tasks dispatched from the task-board get an isolated git worktree
-on `task/<slug>`, so two parallel agents can work on the same repo
-without stepping on each other. PR mode auto-detects `gh` CLI and
-turns "Merge" into "Open PR".
+### 🌳 Worktree-isolated agent dispatch
 
+Code tasks dispatched from the task-board each get an isolated git worktree on
+`task/<slug>`, so parallel agents work the same repo without colliding. PR mode
+auto-detects the `gh` CLI and turns "Merge" into "Open PR".
 See [docs/tasks.md](docs/tasks.md).
 
+### 🔐 Permissions + audit trail
+
+Every utility runs sandboxed and declares an explicit permission allowlist;
+every host-API call is recorded in an append-only audit log you can inspect.
+Sensitive powers (spawning agents, mutating git) require dedicated, consented
+permission slots. See [docs/host-api.md](docs/host-api.md).
+
 ## Architecture at a glance
 
 One Node process. Inside it:
@@ -129,10 +150,8 @@ One Node process. Inside it:
 - Subprocess agents (Claude Code / Codex) spawned per topic.
 - MCP servers on demand.
 
-Two filesystem homes: `REFLEX_HOME` (global state) and
-`<root>/.reflex/` (per-Space).
-
-For the full layer diagram and component map see
+Two filesystem homes: `REFLEX_HOME` (global state) and `<root>/.reflex/`
+(per-Space). For the full layer diagram see
 [docs/architecture.md](docs/architecture.md).
 
 ## Documentation
@@ -146,6 +165,7 @@ For the full layer diagram and component map see
 | [docs/kb.md](docs/kb.md) | Knowledge-base entries, kinds, slug rules |
 | [docs/workflows.md](docs/workflows.md) | Step kinds, templates, scheduler, system tasks |
 | [docs/utilities.md](docs/utilities.md) | Extension model, manifest, permissions, iframe + worker |
+| [docs/sharing.md](docs/sharing.md) | Cross-utility data sharing (the Share Plane) |
 | [docs/host-api.md](docs/host-api.md) | Full `reflex.*` method reference |
 | [docs/markers.md](docs/markers.md) | `<<reflex:*>>` protocol reference |
 | [docs/skills.md](docs/skills.md) | Skill files, scopes, marker authoring |
@@ -163,8 +183,8 @@ reflex chat <dir>             # open a chat scoped to dir's KB
 
 ## Data directory
 
-Reflex stores its global state (registered roots, settings, MCP config,
-secrets, skills, sessions index, …) in one directory:
+Reflex stores its global state (registered roots, settings, MCP config, secrets,
+skills, sessions index, …) in one directory:
 
 - **Dev (`pnpm dev`)** → `~/.reflex`
 - **Prod (`reflex start` via npm-installed CLI)** → `~/.reflex-agent`
@@ -175,13 +195,14 @@ Override either by setting `REFLEX_HOME=/your/path` before launching.
 
 ```sh
 pnpm install
-pnpm dev      # http://localhost:3211 (Next dev server with HMR)
-pnpm build    # produce dist/ + .next/ for `reflex start`
+pnpm dev        # http://localhost:3211 (Next dev server with HMR)
+pnpm build      # produce dist/ + .next/ for `reflex start`
 pnpm typecheck
+pnpm test       # vitest
 ```
 
-PRs welcome. The codebase favours small, focused modules — when in
-doubt, look at neighbouring files and match the style.
+PRs welcome. The codebase favours small, focused modules — when in doubt, look
+at neighbouring files and match the style.
 
 ## Config (`.reflex/config.json`)
 
@@ -193,9 +214,9 @@ doubt, look at neighbouring files and match the style.
 }
 ```
 
-`watchDebounceMs` defaults to 30 minutes (`1800000`). Lower it for
-tighter loops; the enforced minimum is 1 second (anti-thrash).
+`watchDebounceMs` defaults to 30 minutes (`1800000`). Lower it for tighter
+loops; the enforced minimum is 1 second (anti-thrash).
 
 ## License
 
-MIT.
+[MIT](LICENSE) © the Reflex authors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reflex-agent",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "private": false,
   "description": "Local-first knowledge base built by an agent over a chosen directory.",
   "license": "MIT",