Suggest edit — index

Title

Name

Note

---
visibility: public
---

# picortex

*Working name — subject to rename. See [ADR-0001](docs/adrs/0001-standalone-project-not-noos-fork.md).*

A personal variant of [Cortex](https://cortex.ideaflow.app), tuned for one developer: **iMessage + group texting via the Linq partner API**, per-chat **Linux-permission** workspace isolation (no Docker), mobile-first web UI with file browser + web terminal attaching live to the chat's tmux + Claude Code session.

**Status:** Planning phase — no code yet. See [PRD](docs/prd/001-picortex-v1.md) and the [initial roadmap](docs/plans/2026-04-23-initial-roadmap.md).

> ⚠️ **Architecture provisional (2026-04-23).** This README, the PRD, ADR-0003, and Specs 002/003 describe a tmux-centered single-host design. Later in the same session, Jacob reframed the product as "awesome texting experience" (not dev-surface-first), and [prototype-options.md](docs/plans/2026-04-23-prototype-options.md) reopened the core architecture choice. The tmux path is **one option (#1)** of six under consideration. A [Piyush-era study](docs/wiki/piyush-era-design.md) argues Option 2 (`claude -c -p` per turn, two-box physical split) is probably the better v0.1 shape. Do not start implementation until [Q0-Q4 tickets](https://wikihub.globalbr.ai/@jacobcole/picortex) close and the [reconciliation sweep](https://wikihub.globalbr.ai/@jacobcole/picortex) (picortex-357) rewrites this doc against the chosen option.

## Elevator pitch

Cortex (IdeaFlowCo/cortex) has spent the last month solving 90% of the problems this project needs solved — per-chat workspaces, attention gating, scoped tokens, sharing bridge, Linq webhook ingestion, linq-sim dev harness. picortex is a personal spin that keeps Cortex's architecture but:

- **Lighter isolation** — Unix user + filesystem permissions per chat instead of Docker containers
- **Mobile-first from day one** — the split-view betterGPT mockups Jacob already drew
- **Slimmer surface** — no enterprise multi-tenant, no billing, one developer
- **Openchat as a third testing channel** — if/when openchat gets upgraded with a linq-compatible adapter, picortex can run against it without even going through Linq

## Why not fork Cortex directly?

- Cortex is a team/business product with design constraints picortex doesn't have
- Docker-container-per-workspace is the single biggest source of spin-up latency and resource cost — Linux-user isolation is ~100× cheaper and sufficient for single-tenant use
- Picortex is an R&D vehicle for isolation alternatives, which would drag on Cortex's main line
- See [ADR-0001](docs/adrs/0001-standalone-project-not-noos-fork.md) and [ADR-0002](docs/adrs/0002-linux-users-over-docker.md)

## Core capabilities (planned v1)

| Capability | Primary ref |
|---|---|
| iMessage + group text interface via Linq | [spec/006](docs/specs/006-linq-integration.md) |
| Per-chat Linux-user + home-dir isolation | [spec/001](docs/specs/001-workspace-isolation-linux-users.md) |
| Tmux session per chat running Claude Code | [spec/002](docs/specs/002-tmux-session-spawning.md) |
| Web terminal (xterm.js) attaching to live tmux | [spec/003](docs/specs/003-web-terminal-xtermjs.md) |
| File browser (betterGPT split-view) | [spec/004](docs/specs/004-file-browser.md) |
| Attention gating (always / mentions-only / discriminate / silent) | [spec/005](docs/specs/005-attention-gating.md) |
| Mobile-first web UI with thread/reply | [spec/007](docs/specs/007-mobile-first-webui.md) |
| Structured logs + `/api/frontend-log` + version display | [spec/008](docs/specs/008-observability.md) |

## Explicit non-goals (v1)

- No Docker, no Kubernetes, no docker-compose
- No session-management dashboard (Cortex has one; picortex starts with "web terminal attach to tmux session for current chat" only)
- No billing / multi-tenant / team accounts
- No native mobile apps (mobile-first *web* UI only)
- No group-text mobile UI yet (1:1 first)

## Documents

- `docs/prd/001-picortex-v1.md` — PRD v1 (provisional)
- `docs/plans/2026-04-23-initial-roadmap.md` — phased roadmap (Option-1 shape; provisional)
- `docs/plans/2026-04-23-prototype-options.md` — **the live brainstorm** comparing 6 architecture options
- `docs/wiki/piyush-era-design.md` — study of pre-container Cortex; source of Option 2
- `docs/reviews/codex-2026-04-23.md` — codex review of the initial plan
- `docs/specs/` — technical specs per subsystem (provisional)
- `docs/adrs/` — architecture decisions (one per file, Nygard format)
- `docs/wiki/` — Karpathy-style LLM wiki (concept graph)
- `docs/runbooks/` — ops playbooks
- `AGENTS.md` — operational instructions for coding agents (Codex, Claude Code, etc.)
- `CLAUDE.md` → symlink to `AGENTS.md`
- `llms.txt` — LLM sitemap

### Session history
- `~/memory/session-logs/2026-04-23-picortex-planning/` — full JSONL session + cleaned transcript + codex's session-level review (`session-review.md`)
- Public mirror: https://wikihub.globalbr.ai/@jacobcole/picortex
- Documentation best practices that informed this doc set: `~/memory/research/documentation-best-practices-2026-04-23.md`

## Ports

Per [dev-patterns](https://github.com/tmad4000/jacob-computer-config-private) rule: no default ports.

- Dev backend: **7823**
- Dev frontend: **7824**
- Local linq-sim (via Cortex): **8447**

## Quick start (eventual)

```bash
npm install
cp .env.example .env
npm run dev          # backend + frontend + linq-sim orchestrator
npm test             # vitest
```

## Related projects

- [Cortex (IdeaFlowCo)](https://github.com/IdeaFlowCo/cortex) — pattern source
- [noos](~/code/noos) — potentially overlapping (knowledge graph + Slack bot); see [wiki/relationship-to-noos.md](docs/wiki/relationship-to-noos.md)
- [openchat](~/code/openchat) — candidate third channel once linq-adapter lands
- [voice-assistant](~/code/voice-assistant) — predecessor with overlapping tool set (file system, run_command, Claude spawning); see [wiki/relationship-to-noos.md](docs/wiki/relationship-to-noos.md)