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

At a glance

How it runs
Self-hosted serviceWeb appDesktop app
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
Node.js 22.19.0 or newerClaude Code CLI executable (optional)Codex CLI executable (optional)Pi CLI executable (optional)Pi SDK 1.5.2OpenAI API keyElevenLabs API key (optional)Shell / CLINetwork accessLocal filesystemMCP Server
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

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).

  1. Developers already running Claude Code or Codex who want task lists, meeting notes and agent chat in one panel workspace
  2. Users who want a self-hosted personal assistant that keeps notes and session logs on their own machine instead of a cloud SaaS
  3. Heavy voice users who want the same workspace across a desktop browser and an Android device
  4. People scheduling cron-driven CLI agent runs for routine jobs such as a daily roundup
  5. Developers writing custom panels and CLIs for internal workflows with the plugin SDK
  6. 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_DIR APP_CONFIG_PATH ELEVENLABS_API_KEY ELEVENLABS_TTS_VOICE_ID ELEVENLABS_TTS_MODEL
Config files
packages/agent-server/data/config.json packages/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 build

Start the server (built-in config lives at packages/agent-server/data/config.json):

npm run start -w @assistant/agent-server

Then 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-server

Optional 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_v2

Full 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?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
38/ 100 5-point scale 1.9 / 5
Trust 10/29
Reliability 5/14
Adaptability 8/18
Convention 8/18
Effectiveness 4/13
Verifiability 3/8
Why each dimension lost points
Trust10 / 29 · 1.7/5

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.

Reliability5 / 14 · 1.8/5

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.

Adaptability8 / 18 · 2.2/5

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.

Convention8 / 18 · 2.2/5

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.

Effectiveness4 / 13 · 1.5/5

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.

Verifiability3 / 8 · 1.9/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 16, 2026 Reviewed revision 101db5745a1d
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/assistant.svg)](https://followagents.com/en/agents/assistant)
<a href="https://followagents.com/en/agents/assistant"><img src="https://followagents.com/badge/assistant.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. 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?
Both paths exist. In-process chat goes through Pi SDK 1.5.2 using named chatProfiles of ordered provider/model choices, and locally installed Claude Code, Codex or Pi CLIs can run as subprocess agents alongside it.
Where does my data live?
On your self-hosted machine: the session index is ${DATA_DIR}/sessions.jsonl, each session's events are in ${DATA_DIR}/sessions/<sessionId>/events.jsonl, and config defaults to ${DATA_DIR}/config.json. Lists, notes and time-tracker can additionally auto-commit to Git.
Does voice cost extra?
Speech input uses the browser's Web Speech API with no extra key. Speech output uses OpenAI TTS by default or optional ElevenLabs streaming TTS, which the README warns can be costly and needs your own API key.
Can Claude Code or Codex use its notes and lists directly?
Yes. npm run build:plugins -- --skills-dir <dir> exports plugins as skills; copy them into ~/.claude/skills/, ~/.codex/skills/ or ~/.pi/skills/. Some skills ship CLIs such as notes-cli and lists-cli.
Is it suitable for production or a team deployment?
The README opens by calling it personal software shared for educational purposes without stability or support; teams needing an operable system with SLAs should evaluate carefully or look elsewhere.
Is Assistant Workspace open source?
The source code is public on GitHub (kcosr/assistant), but the repository does not declare a recognised licence, so the rights to reuse or modify it are unclear. Ask the author or check the README before building on it.
Is Assistant Workspace safe to use?
FollowAgents' FARS review (Nov 16, 2026) scored Assistant Workspace 10/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Assistant Workspace still maintained?
Yes. The latest commit on GitHub is from 2026-11-15, within the last 30 days.
Who makes Assistant Workspace?
Assistant Workspace is published on GitHub by the account kcosr. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts