TwiCC (The Web Interface for Claude and Codex) is a self-contained web UI. It browses and drives Claude Code and Codex sessions. One process, no external service.
This file is shared by Claude (CLAUDE.md) and Codex (AGENTS.md). Lines marked Claude: or Codex: apply to that provider only.
- Quality: use the best standards. The only allowed shortcut: tests and linting are not mandatory.
- Never implement without an explicit invitation. An explanation of requirements is not an invitation. Ask questions, then wait.
- Preserve user changes. The checkout can contain uncommitted changes you did not make. Do not revert, overwrite, move or clean them.
- No working-tree-wide git commands on a shared checkout. Several agents and the user can work in the same checkout at the same time. A command that changes the whole tree removes their files from disk for a while, or for good. Never run
git stash,git checkout -- <path>,git restore,git reset --hard,git clean, orgit checkout <ref>to switch branches. To compare withHEAD, usegit show <ref>:<path>,git diff, or a temporarygit worktreeoutside the checkout. Do these only on explicit request. - Rebase: never on a remote branch (
origin/main, …) unless asked. Rebase on the local branch. - Language: write all artifacts in English: code, source UI messages, comments, names, docs (incl.
docs/plans/). Translated UI messages belong infrontend/src/i18n/locales/; seedocs/internationalization.md. French is for live chat only. - Internationalization: all application-owned text displayed in the interface must use i18n. This includes labels, tooltips, errors, toasts and backend messages displayed in the UI. Follow Internationalization for catalogs, localized help/tips and deliberate English-only exceptions.
- Plans and specs location: write every spec, design and implementation plan in
docs/plans/, whatever skill produces it (Superpowers or other). Never write indocs/superpowers/. This overrides the skill's default path. - Local instructions: Claude:
CLAUDE.local.mdloads automatically. Codex: ifAGENTS.local.mdexists at the repo root, read it after this file. It extends this file and wins on conflict. Direct system, developer and user instructions win over both.
- Subject: Conventional Commit,
type(scope): summary, lowercase summary (feat,fix,docs,refactor,test,chore, …). - Always add a body that explains the change.
- Trailer, with the exact name of the model you run as now (never hardcode it):
- Claude:
Co-Authored-By: Claude MODEL <noreply@anthropic.com>. - Codex:
Co-Authored-By: Codex MODEL <codex@openai.com>.
- Claude:
- CHANGELOG: write it only on explicit request. Write only in
## [Unreleased](create it at the top if absent). Never edit a dated release section (## [X.Y.Z] - DATE). Re-read the top of the file first: an[Unreleased]line can be promoted into a release between turns. If so, add a new[Unreleased]entry. - Releases: follow
docs/release-process.md.
Do not run these on your own initiative. On explicit request, run them without confirmation. Otherwise, remind the user at the end of the task.
- Django
migrateafter you create a migration. (devctl.py startapplies migrations itself.) - Dev server restart after backend changes (via
devctl.py). - Package installation (
npm install,uv add). On request:cd <target> && uv add <pkg>. Neveruv pip install.
uv + npm · Django 6 ASGI (Uvicorn, Python ≥ 3.13) · Channels (in-memory layer) · SQLite (WAL) · watchfiles · claude-agent-sdk + openai_codex · Vue 3 (<script setup>) + Vite 7 · Pinia + VueUse · Web Awesome 3 (wa-*) · CodeMirror 6 · xterm.js · markdown-it + shiki + mermaid.
-
Python: always
uv run python …oruv run <tool>(uvx <tool>for a tool absent from the project). Never a barepython,pytest,mypyor other Python tool: the backend removes its own venv from what it launches (strip_own_python_env,src/twicc/server_env.py), so a bare command finds the system one, not the project's. -
Lint:
uvx ruff check .(ruff is not installed;uv run rufffails). Run any absent Python tool withuvx <tool>. Neveruv adda tool to make a command work. -
Python tests:
cd <checkout> && uv run pytest.twicc.settings_testisolates data dir, provider homes and DB, and forbids the real data dirs. Never addTWICC_DATA_DIR=to a pytest command. Each test has a 120-second limit (timeoutinpyproject.toml). Opt-in integration tests and benchmarks have none. -
Frontend tests:
cd frontend && npm test. -
Codex real-binary tests (
tests/test_codex_migration_integration.py): skipped unlessTWICC_CODEX_INTEGRATION=1. -
Scripted test loops (mutation testing, …): launch each run as
timeout -k 5 <seconds> <command>. Never usesubprocess.run(["uv", "run", …], timeout=…): it killsuvonly, and the test process survives as an orphan. -
Hermetic LLM diagnostic: run
uv run python scripts/diagnose_hermetic_llm.py --provider all --live --yesafter one of these changes:- the small Codex model (
TITLE_MODEL,_REFRESH_MODEL); - a Codex or vendored Codex SDK update (
docs/codex-vendoring.md); - a Claude Agent SDK update.
Do not ship on
FAILorINCONCLUSIVE. - the small Codex model (
-
Claude SDK updates: also run
uv run python scripts/diagnose_claude_title_sync.py --live --yes --json. This verifies the private persistent-session title control against the real bundled CLI. Do not ship onFAILorINCONCLUSIVE. Record both SDK and CLI versions. Required checks and isolation:docs/claude-sdk-updates.md.
| Command | Targets | |
|---|---|---|
uv run · uv sync · uv add |
the project of the cwd | ✅ |
uvx <tool> |
nothing (ephemeral) | ✅ |
uv pip … · anything with --active |
the ACTIVE environment | ❌ |
The backend removes its own venv (VIRTUAL_ENV and its bin/ on PATH) from what it launches. A process can still carry the MAIN repo's VIRTUAL_ENV: a tmux server started by an earlier backend, or a shell you set up yourself. There, the ❌ forms sync the project into the MAIN repo's venv: from a worktree, they make the main repo import the worktree's sources. The does not match the project environment path warning means such a foreign VIRTUAL_ENV: never "fix" it with --active.
To check which sources you run: uv run python -c "import twicc; print(twicc.__file__)". The path must be inside your checkout.
- Resolution in
src/twicc/paths.py:$TWICC_DATA_DIRif set, else~/.twicc/(the prod data dir). paths.pydoes not detect worktrees. Onlydevctl.pysetsTWICC_DATA_DIR=<worktree root>.- The
.envin the data dir wins over the inherited environment.TWICC_DATA_DIRcomes only from the environment. - Provider homes (
CLAUDE_CONFIG_DIR,CLAUDE_SECURESTORAGE_CONFIG_DIR,CODEX_HOME) come only from the.env. Read every provider path throughsrc/twicc/provider_homes.pyat call time, never as an import-time constant. Give every launched processprovider_env_overlay(). Design:docs/plans/2026-09-02-provider-home-dirs-design.md. - Contents and backups: see
src/twicc/paths.pyandsrc/twicc/data_backups.py.
uv run ./devctl.py start|stop|restart [front|back|all]
uv run ./devctl.py status
uv run ./devctl.py logs [front|back] [--lines=N]
uv run ./devctl.py kill-tmux # worktrees only- Default ports: frontend 5173, backend 3500. Debug with
<data_dir>/logs/{backend,frontend}.log. - To start, run one
startcommand and read the logs. devctl runsnpm ci, applies migrations, and in a worktree copies the DB and user config, picks free ports and writes the.env. - Never run
npm install/npm ci,migrate, or touchnode_modulesto start servers. A parallelnpm installcorrupts devctl'snpm ci(ENOTEMPTY). - A post-start port-check timeout during initial sync is not a failure. Confirm in
backend.log.
- Each worktree has its own data dir:
.env(ports),.devctl/,db/,logs/, JSON data files. - Never share dependencies or build files through links. Never create symbolic links or hard-linked copies of
node_modules(at any depth),.venv, build outputs or caches between checkouts or verification directories. Each checkout owns these files. Use independent installations or independent copies, subject to the package-installation rules above. - Python commands can trigger frontend installation.
uv runcan build TwiCC throughhatch_build.py, which runsnpm ci. That command emptiesnode_modulesbefore reinstalling. A link can therefore delete another checkout's dependencies even when the command only runs Python tests. - No other ad hoc links for shared files or directories. The existing exceptions are
artifacts/andscratch/, linked to the main data dir bydevctl.py(SHARED_LINK_DIRS). Letdevctl.pymanage those links. Do not extend these exceptions. - Prefix every Bash command with
cd <worktree> &&. A wrong cwd ondevctl stop/restartormigratehits the main servers and data. - Give the user the localhost URLs that devctl prints.
start --empty-db: fresh DB.start --fresh-providers: fresh DB plus the worktree's own empty provider homes. Otherwise the worktree shares the provider homes of its.env(by default the real~/.claude/~/.codex).- To exit or delete a worktree, always run
stop allthenkill-tmux, even if you did not start the processes. - A worktree backend lets direct loopback requests skip the password. All password checks go through
src/twicc/auth/access.py. Never write one inline.
Without TWICC_DATA_DIR, Python or Django outside devctl (manage.py, shell, one-liners) uses ~/.twicc/, even after cd. A migrate there applies branch migrations to the prod DB. Do both steps, then check the DB path:
cd <worktree>
TWICC_DATA_DIR=$PWD uv run python -m django <command> --settings=twicc.settings
# check: settings.DATABASES['default']['NAME'] must be inside the worktree- Entry:
run.py → cli.main()(src/twicc/cli/). Startup: initial sync of provider roots intoSessionItemrows, then a background compute process fills metadata (compute_version). - Django ASGI (
src/twicc/asgi.py): REST + SPA, WebSocket/ws/(UpdatesConsumer) and/ws/terminal/<session_id>/(PTY). - Watcher (
src/twicc/providers/sessions_watcher.py): JSONL files are append-only. On change, read fromlast_offset, save, broadcast over WS to Pinia. - Agent managers drive provider SDKs (
src/twicc/providers/). Providers write JSONL. The watcher picks it up. - Periodic tasks (price sync, usage quotas):
src/twicc/pricing_task.py,src/twicc/usage_task.py. - MCP server:
src/twicc/mcp/. A new CLI command auto-adds its RPC route and MCP tool. Kill switch:TWICC_NO_MCP=1. - Models:
src/twicc/core/models.py. Frontend:frontend/src/. Designs:docs/plans/.
- Python style:
orjson, never stdlibjson.NamedTuplefor immutable data. Import aliases (as) only for a real name collision or a needed intent clarification. - Timeline: write
TimelineEventonly throughrecord_event/record_event_sync(src/twicc/core/services/session_timeline.py). Never insert directly. Never use Django signals (the code usesqueryset.update()). Designs:docs/plans/*timeline*-design.md. - Agent settings: the seven per-session fields are a closed bundle with one shape for all providers. A new provider flag is a new
Sessioncolumn, classified in the provider'sgetAgentSettingsCategories()(frontend/src/providers/). Never a side table. - Project defaults resolve at session creation only, in two mirrors:
frontend/src/utils/projectAgentDefaults.jsandsrc/twicc/project_agent_defaults.py. Keep them in sync. - Trust is human-only. Never expose it as an agent flag or skill.
permission_mode_if_untrustedis never aSessionfield. Seesrc/twicc/core/services/trust.pyanddocs/archives/plans/2026-06-09-project-trust-design.md.
HTML artifacts use plain fetch(). TwiCC proxies it after a per-host user consent. These are the design, not gaps. Do not "harden" them:
- Hard-block only the cloud metadata address (
169.254.169.254/fd00:ec2::254). Never range-block loopback, LAN or public addresses. - Forward headers verbatim,
Authorizationincluded (only hop-by-hop and similar mechanical drops). - Consent is client-side (
frontend/src/artifact-broker/host.js). Do not add a consent check tosrc/twicc/artifacts/proxy.py. - The iframe CSP
connect-src 'none'is the egress boundary. The shim is DX, not security.
The in-SPA preview and the /artifacts/<id>/ page share frontend/src/composables/useArtifactBroker.js. Never re-implement one side. Design: docs/archives/plans/2026-06-18-artifact-network-broker-design.md.
- Not HMR'd bundles: after you edit
frontend/src/artifact-broker/,artifact-shell/,artifact-theme/,browser-companion/,share-session/,share-recent/orelement-select/, runcd frontend && npm run build. - Circular imports break HMR. Never import
router.jsstatically from utils, composables or stores: useawait import('../router'). Break store↔store and store↔composable cycles with a lazyimport(). UsedefineAsyncComponentwhen a composable imports a component that closes a cycle. - Public assets:
frontend/public/is served at/in dev but at/static/in the build. A raw/icons/foo.svgstring breaks only on the backend. Always useresolvePublicAssetUrl()(frontend/src/utils/publicAsset.js). - Item content: never read
item.contentdirectly, neverJSON.parseit, never touch_parsedContent. UsegetParsedContent/setParsedContent/clearParsedContentfromfrontend/src/utils/parsedContent.js. UsehasContent(item), not!!item.content: synthetic items have parsed content but no raw string. - Iframes: an iframe reloads when its node moves. Embedded pages render through
PersistentFrame(frontend/src/components/frames/). Never<Teleport>an iframe. Never reorderFrameHost's registry. - Dialog forms: copy
frontend/src/components/project/ProjectEditDialog.vue(agents often get these wrong):- Wrap the content in a
<form id="…" @submit.prevent="handleSave">. - Put the submit button outside the form:
type="submit", and set itsformattribute withsetAttribute()(wa-buttondoes not exposeformas a property). - Focus the first input in
@wa-after-show, never withautofocus. Put the cursor at the end withsetSelectionRange(len, len). trim()text inputs before validation and submit. Check uniqueness client-side first.- Show errors in
wa-callout variant="danger". - Width:
--width: min(Xpx, calc(100vw - 2rem)). - Guard
@wa-show/@wa-hide/@wa-after-*handlers against bubbling from nestedwa-*children (see Web Awesome).
- Wrap the content in a
- Import every component explicitly in
frontend/src/main.js. A missing import works in dev and is unstyled in prod. - Native events are unprefixed (
@click). Custom events keepwa-(@wa-show). - Icon slots (agents often get these wrong): in a button, use
slot="start"/slot="end", neverprefix/suffix. In awa-dropdown-item, useslot="icon".<wa-button><wa-icon slot="start" name="check"></wa-icon> Save</wa-button> <wa-dropdown-item><wa-icon slot="icon" name="plus"></wa-icon> New</wa-dropdown-item>
- Custom events bubble. A nested
wa-selectin awa-dialogfireswa-show/wa-hideon the dialog. Scope every handler to its own element:event.target !== event.currentTargetguard,.self, or.stop. - Docs:
frontend/node_modules/@awesome.me/webawesome/dist/llms.txt.
- Skills live in
src/twicc/agent/plugin/twicc/skills/. Readsrc/twicc/agent/plugin/README.mdbefore you create or edit one. - Every
SKILL.mdchange requires aversionbump insrc/twicc/agent/plugin/twicc/.claude-plugin/plugin.json. Otherwise providers serve a stale cached copy. Patch for a user-visible change; minor for a new skill, new flags, a rename or a removal.