Assistant Workspace
A panel-based personal assistant where Claude Code, Codex and Pi agents share notes, lists and other panels with you in one workspace.
- Source repo
- kcosr/assistant
- Stars
- ★ 92
- Last updated
- 6d ago
- Primary language
- TypeScript
- FA score
- 38/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers already running Claude Code or Codex who want task lists, meeting notes and agent chat in one panel workspace
- Not a fit if
- Teams needing stable, supported production software
- Users who won't host a Node.js server and manage config and keys
- People unwilling to keep notes and session logs on a self-hosted machine
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-15latest release v0.18.2 (2026-04-06) · pre-release
- Source review
- 38/100 · Major gaps
What does this agent do, and when should you use it?
Assistant is an experimental, self-hosted personal AI assistant built on an npm-workspaces monorepo: a Node.js agent-server exposing WebSocket (chat and binary audio) plus HTTP (static files and REST API), and a browser web-client rendered as a panel layout. Chat, notes, lists, time tracking and other workflows live in plugin-defined panels, so AI agents and the user operate on the same workspace data. Agents can be in-process Pi SDK chats configured through named chatProfiles, or subprocesses of locally installed Claude Code, Codex and Pi CLIs, with additional tools attached over MCP (JSON-RPC 2.0 on stdio). Input supports browser Web Speech API recognition; output optionally uses OpenAI TTS or ElevenLabs streaming TTS, and Android adds an openai-speech-server voice path. Sessions persist as append-only JSONL event logs with built-in tools for listing, searching, creating, switching, renaming and pinning sessions, and multiple browser windows can share one session. Plugins can be exported as skills with CLIs for Claude Code, Codex and Pi, and the repo also ships Electron, Tauri and Capacitor wrappers plus a push-notification proxy. The author states this is personal software shared for educational purposes, without stability or support guarantees.
agent-server listens on WebSocket for chat control, text and binary audio frames, and on HTTP for static assets and a REST API. Each session is an append-only JSONL ChatEvent log at ${DATA_DIR}/sessions/<sessionId>/events.jsonl, indexed in ${DATA_DIR}/sessions.jsonl, which is how several browser windows can share one conversation. Agents come from config.json: in-process Pi agents reference named chatProfiles of ordered provider/model choices with per-model thinking levels, while CLI agents are launched as subprocesses (Claude, Codex, Pi); scheduled sessions allow cron-driven CLI runs. Built-in session tools let the agent list, search, create, switch, rename and pin sessions. Plugins declare panels and operations, so the agent can read and mutate lists, notes and time-tracker panels through plugin CLIs such as notes-cli, lists-cli and time-tracker-cli, all of which accept --json. Plugin build scripts export plugins as skills into a directory, and lists, notes and time-tracker auto-commit their data directories to Git on a configurable interval (1 minute by default).
- Developers already running Claude Code or Codex who want task lists, meeting notes and agent chat in one panel workspace
- Users who want a self-hosted personal assistant that keeps notes and session logs on their own machine instead of a cloud SaaS
- Heavy voice users who want the same workspace across a desktop browser and an Android device
- People scheduling cron-driven CLI agent runs for routine jobs such as a daily roundup
- Developers writing custom panels and CLIs for internal workflows with the plugin SDK
- Technical users who want the agent to reach existing local tooling through MCP servers
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Ports
3000- Environment variables
DATA_DIRAPP_CONFIG_PATHELEVENLABS_API_KEYELEVENLABS_TTS_VOICE_IDELEVENLABS_TTS_MODEL- Config files
packages/agent-server/data/config.jsonpackages/agent-server/data/config.example.json- Runtime
- Node.js 22.19.0
How do you install or deploy this agent?
Node.js 22.19.0 or newer is required; CLI agent providers need their own separately installed executables. Clone and build:
git clone https://github.com/kcosr/assistant
cd assistant
npm install
npm run buildStart the server (built-in config lives at packages/agent-server/data/config.json):
npm run start -w @assistant/agent-serverThen open http://localhost:3000 in a browser. To override data or config paths:
export DATA_DIR=/path/to/data
export APP_CONFIG_PATH=/path/to/config.json
npm run start -w @assistant/agent-serverOptional ElevenLabs streaming TTS (the README notes it can be costly):
export TTS_BACKEND=elevenlabs
export ELEVENLABS_API_KEY=<key>
export ELEVENLABS_TTS_VOICE_ID=VUGQSU6BSEjkbudnJbOj
export ELEVENLABS_TTS_MODEL=eleven_multilingual_v2Full options are documented in docs/CONFIG.md and packages/agent-server/data/config.example.json.
How do you use this agent?
Open the panel UI at http://localhost:3000; Ctrl/Cmd + K opens the command palette, Ctrl/Cmd + ] and [ cycle panel focus, Ctrl + I focuses text input, Ctrl + R toggles speech recording. To give external CLI agents the plugin skills, build them and copy into the agent's skills directory:
npm run build:plugins -- --skills-dir /tmp/skills
cp -r /tmp/skills/{notes,lists} ~/.pi/skills/Or build only selected skills straight into the directory (Claude uses ~/.claude/skills/, Codex ~/.codex/skills/):
npm run build:plugins -- --skills notes,lists --skills-dir ~/.pi/skills/Skills that ship a CLI need their directories on PATH or a full path reference:
export PATH="$PATH:$HOME/.pi/skills/notes:$HOME/.pi/skills/lists"Git auto-snapshots can be disabled per plugin in config.json:
{
"plugins": {
"lists": {
"enabled": true,
"gitVersioning": {
"enabled": false
}
}
}
}What are this agent's strengths and limitations?
- Panel layout plus a plugin SDK: notes, lists and time tracking are extensible panels rather than a fixed feature list
- One workspace spans in-process Pi SDK model chat and Claude Code, Codex and Pi CLI subprocesses, with built-in session management tools
- Plugins export as skills with CLIs, so Claude Code, Codex and Pi reuse the same notes/lists/time-tracker capabilities
- JSONL append-only session logs with multi-window sharing, and Git auto-snapshots on lists, notes and time-tracker by default
- Multiple client wrappers (Electron, Tauri, Capacitor) and a push proxy, while self-hosting needs only Node.js
- Explicitly labeled experimental personal software with no stability or support guarantees
- Runtime floor is Node.js 22.19.0 plus Pi SDK 1.5.2, and each CLI provider must be installed separately
- Repository metadata lists the license as unknown even though the README says MIT — verify before adopting
- Voice input depends on the browser Web Speech API and TTS output depends on paid OpenAI or ElevenLabs services
- No evidence of a Chinese UI or Chinese-language docs; configuration and skill references are English-only
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Assistant Workspace This agent | 38 · Major gaps | Self-hosted serviceFree + model costs | ★ 92 | 6d ago | TypeScript | Codex · Claude Code · OpenAI API |
| Lotti Private Logbook | 78 · Good | Desktop appFree + model costs | ★ 1.2k | today | Dart | OpenAI API · Claude API |
| Waku | 65 · Some gaps | CLIFree + model costs | ★ 2.2k | 1d ago | Python | OpenAI API · Claude API |
| Qwen Audio Agent | 70 · Some gaps | CLIFree + model costs | ★ 3.3k | 3d ago | JavaScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows tool allow/deny lists, explicit opt-in for Realtime tools, restricted permission profile for web_search, and a static-token auth design doc, indicating least-privilege awareness. However TOOL_APPROVALS.md is explicitly a draft with 'no current code references', so panel tool approval is unimplemented and user confirmation is weak. Sensitive data: CONFIG.md states API keys stay server-side and never reach clients, but WS token via query param risks log leakage. Dependency security shows only version ranges, no audit or lock evidence. Rollback: git versioning is on by default for lists/notes/time-tracker but only covers plugin data, not globally. Source attribution is limited to README MIT claim and author. Thin evidence, so 1 across.
README and package.json agree on Node >=22.19.0 and Pi SDK 1.5.2, with build/test scripts present; but CLI providers require separately installed executables, so dependency availability depends on external environment. Failure messages exist in push-cli and notify-proxy but overall error handling evidence is limited. Self-consistency has some doc/code correspondence but the sample is incomplete, so 1.
README covers text/voice, multiple CLI agents, plugins, mobile and desktop, a broad scenario set (2); but capability boundaries (which tools are enabled by default, missing approvals) are incompletely described, trigger precision relies on suggested AGENTS.md text rather than enforcement, and environment fit (systemd, Android build) points to out-of-repo skills, so 1.
README has TOC, repo layout, and doc map, good information architecture (2); install steps are clear (2); but naming stability, FAQ, known limitations (only an 'experimental software' note), license (README says MIT but metadata unknown), versioning (AGENTS.md describes CHANGELOG flow but no CHANGELOG file shown), and maintenance responsibility (personal project, no support promise) are all thin, so 1.
Feature-rich product, but output usability depends on runtime; as an Agent product it lacks approvals, permission boundaries, and verifiable default-safe configuration, and marginal value/cost-benefit cannot be confirmed statically, so 1 across.
README claims cross-corroborate with some code/docs (Pi SDK version, config paths), but most security and behavior claims lack test or code references; TOOL_APPROVALS is explicitly unimplemented design. Fact/inference separation is acceptable but evidence is thin, so 1.
- Panel tool approvals (TOOL_APPROVALS.md) remain a draft with no code implementation, so agent actions on panels lack a user-confirmation layer.
- WebSocket auth token is passed via query parameter, which may leak through logs, proxies, or browser history; the static token is not a full auth system.
- README self-describes as experimental personal software with no stability or support guarantee; license metadata is unknown and should be verified before use.
- CLI providers require separately installed executables; dependency availability and version compatibility must be verified independently.
- Git versioning covers only some plugin data, not a global rollback mechanism.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.18.2 Pre-release
Release notes excerpt
Breaking Changes Added - Added chat.thinking support for claude-cli agents: the composer now surfaces the thinking picker for Claude agents, and the selected level is translated to Claude's --effort flag (none/off suppress the flag, xhigh maps to max, and low/medium/high/max pass through) ([#92](https://github.com/kcosr/assistant/pull/92)). - Added a native Android voice setting in the web voice settings menu to enable or disable the local recognized stop command ([#92](https://github.com/kcosr/assistant/pull/92)). Changed Fixed …View on GitHub ↗
FAQ
Does it call models itself, or do I need an external CLI?
Where does my data live?
Does voice cost extra?
Can Claude Code or Codex use its notes and lists directly?
Is it suitable for production or a team deployment?
Is Assistant Workspace open source?
Is Assistant Workspace safe to use?
Is Assistant Workspace still maintained?
Who makes Assistant Workspace?
Thanks — we use this to improve the page.