q-ai-note

AI-assisted personal work sandbox and diary system.

Documentation

Project specs and development guides are organized under docs/:

• docs/spec/functional-spec.md
• docs/spec/design-spec.md
• docs/spec/ui-spec.md
• docs/process/development-guide.md

Install

Use without global install:

npx @qnote/q-ai-note

Install globally:

npm i -g @qnote/q-ai-note
q-ai-note
q-ai-note-server

Usage

q-ai-note --port 3200
q-ai-note .
q-ai-note --readonly

Then open http://localhost:3200.

Command differences

• q-ai-note: local-first, defaults 127.0.0.1:3000
• q-ai-note-server: public server, defaults 0.0.0.0:8614

Public server mode

If you need external access, use:

q-ai-note-server
q-ai-note-server --readonly

Defaults:

• host: 0.0.0.0
• port: 8614

Then open http://<server-ip>:8614.

Access control model

The app now uses two-level configuration:

• system config (~/.q-ai-note/config.json): model settings + editable_ip_allowlist
• project config (<data-dir>/project-config.json): users / profiles / bindings

Rules:

• IP matching is exact match only (no CIDR)
• local loopback and local NIC IPs are system-admin by default
• system-admin IPs can access all pages and full read/write (unless global --readonly)
• non-admin IPs are controlled by project profiles (page visibility + sandbox-level read/write)
• /api/settings (system settings) is only accessible to system-admin IPs

Readonly mode

Use --readonly (or env Q_AI_NOTE_READONLY=true) to start in readonly mode:

• hide chat UI and chat buttons
• hide settings page
• hide add/edit/delete operations
• reject all write API requests (403)
• reject settings API (/api/settings) for readonly requests (403)

Data and config paths

• Config: ~/.q-ai-note/config.json
• Data dir: ~/.q-ai-note/data/
  • project-config.json
  • sandboxes.json
  • work-items.json
  • diaries.json
  • chats.json
  • chat-sandbox-relations.json
  • operations.json

You can override runtime paths with environment variables:

• Q_AI_NOTE_CONFIG_DIR
• Q_AI_NOTE_DATA_DIR

Backward-compatible legacy variables are still supported:

• PERSONAL_AI_NOTEBOOK_CONFIG_DIR
• PERSONAL_AI_NOTEBOOK_DATA_DIR

Publish to npm

npm login
npm publish --access public