derot 0.1.0__tar.gz

derot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rootonchair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

derot-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: derot
+Version: 0.1.0
+Summary: One terminal console for every Claude Code and Codex session across projects, accounts and machines
+Author: rootonchair
+License: MIT
+Project-URL: Homepage, https://github.com/rootonchair/derot
+Project-URL: Issues, https://github.com/rootonchair/derot/issues
+Project-URL: Changelog, https://github.com/rootonchair/derot/blob/main/CHANGELOG.md
+Keywords: claude,claude-code,codex,tmux,tui,terminal,ssh
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=4.0
+Requires-Dist: pyyaml>=6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21; extra == "test"
+Requires-Dist: pyflakes; extra == "test"
+Dynamic: license-file
+
+# derot
+
+[![tests](https://github.com/rootonchair/derot/actions/workflows/tests.yml/badge.svg)](https://github.com/rootonchair/derot/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Stop coding-agent sessions rotting in forgotten terminals.** derot is one terminal console
+for every **Claude Code** and **Codex** session you run: across **projects**, **accounts** and
+**machines** (this computer plus any machine you can SSH into), in one list.
+See which sessions need you, watch the agent work, and type into any of them without leaving
+the console.
+
+![derot: a session needs approval, its live screen on the right](docs/screenshots/overview.svg)
+
+## Features
+
+**Every session at a glance.** Sessions that need you (a permission prompt or a question
+with options) sort to the top, then finished ones, then the ones still working. The summary
+bar counts them, and you get a desktop notification when a session needs you.
+
+**Watch the agent work.** The right-hand panel shows the selected session's details and
+its live screen, exactly as Claude Code or Codex draws it, for local and SSH sessions alike.
+
+![a session working on a remote GPU machine](docs/screenshots/working.svg)
+
+**Type into any session from the console.** Press Enter or click the right panel and every
+key goes straight to Claude: slash commands, `/model`, menus, autocomplete, Esc, paste. Press
+`1`–`9` on the list to answer a prompt in one keystroke, or `f` for Claude's own full-screen
+UI. `Ctrl-q` always brings you back.
+
+![typing into a session: Claude's slash-command menu in the preview](docs/screenshots/typing.svg)
+
+**Pick up old conversations.** `R` lists a session's past conversations with their titles,
+age and last prompt, and resumes the one you pick. `c` continues the session's own last
+conversation.
+
+![the resume picker](docs/screenshots/resume.svg)
+
+**No YAML required.** Add sessions, machines and accounts from forms. The project folder
+field lists matching folders as you type, on the chosen machine (over SSH for remote ones),
+and the SSH target field lists hosts from your `~/.ssh/config` and `known_hosts`.
+
+![new session form with folder suggestions from an SSH machine](docs/screenshots/new-session.svg)
+
+![add machine form with SSH targets](docs/screenshots/add-machine.svg)
+
+**Claude Code and Codex side by side.** Each account belongs to an agent, so Claude Code
+and OpenAI Codex sessions share one list, with the same status, preview, typing and resume.
+
+![a Codex session working next to Claude Code sessions](docs/screenshots/codex.svg)
+
+**Sessions outlive the console.** Every session runs in tmux, so it keeps going when you
+quit derot, close the laptop lid or lose the SSH connection.
+
+## How it works
+
+- **tmux**: each session is a tmux session `cc-<name>` on a private tmux server
+  (`tmux -L derot`), so it survives detaching and never touches your own tmux setup.
+- **SSH**: remote hosts are reached with plain `ssh` (shared ControlMaster connection, one
+  call per host per refresh). Nothing runs on the VM besides tmux, python3 and the agent.
+- **Hooks**: `derot setup` installs a tiny stdlib-only script, `~/.derot/hook.py`, and
+  registers it as a Claude Code or Codex hook (both agents have the same hook events). It writes `~/.derot/state/<name>.json` on each event
+  (prompt submitted, tool use, permission prompt, stop), so status is accurate without screen
+  scraping.
+- **Accounts**: each account is an agent's config folder, with its own login and settings:
+  a Claude Code folder passed via `CLAUDE_CONFIG_DIR`, or a Codex folder passed via
+  `CODEX_HOME`. For Codex, setup registers the same hook in that folder's `hooks.json`.
+
+## Install
+
+Requirements: Python 3.9+, [tmux](https://github.com/tmux/tmux), and
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or
+[Codex](https://developers.openai.com/codex) on every machine you use.
+Developed and used on macOS; the Linux code paths (tmux, `notify-send` notifications) are
+covered by CI but haven't seen much real use yet.
+
+```sh
+pipx install git+https://github.com/rootonchair/derot     # or: uv tool install git+https://github.com/rootonchair/derot
+```
+
+On macOS, `brew install tmux pipx` first. Each SSH machine needs `tmux`, `python3`, the
+agent(s) you use there, and key-based SSH access (`ssh my-vm true` works without a password
+prompt).
+
+## Setup
+
+1. Run `derot`. On first run it creates `~/.config/derot/config.yaml` (override with
+   `DEROT_CONFIG`) and opens the console.
+2. Press `n` to add a session: pick a machine, a project folder (matching folders are listed
+   as you type) and a Claude account. Choose **+ add a machine (SSH)…** or **+ add an account…** in the dropdowns
+   to create those on the spot. Saving installs the status hooks for any new machine/account
+   automatically, and offers to log in to a new account right away.
+3. Press `Enter` on a session to start it and type into it from the right panel; `Ctrl-q`
+   stops typing. `f` opens Claude's own full-screen UI instead.
+
+No YAML editing needed. `e` edits the selected session, `d` removes it, `l` logs in to the
+session's account (Claude Code opens so you can `/login`; for Codex it runs `codex login`). The config file is still plain YAML if you
+prefer it (`E` opens it in `$EDITOR`); saving from the console rewrites it without comments
+and keeps your original as `config.yaml.bak`.
+
+A VM needs tmux, python3, Claude Code and/or Codex, and key-based SSH (`ssh my-vm true`
+works without a password prompt). From the command line, the same setup is `derot login ACCOUNT [--host H]`
+and `derot setup`.
+
+<details><summary>Config file reference</summary>
+
+```yaml
+hosts:
+  vm:
+    ssh: user@my-vm            # anything `ssh` accepts, incl. ~/.ssh/config aliases
+    claude: claude             # optional: command/full path for Claude Code there
+    codex: codex               # optional: command/full path for Codex there
+accounts:
+  personal: {config_dir: ~/.claude}
+  openai: {agent: codex, config_dir: ~/.codex}   # agent: claude (default) or codex
+  work:
+    config_dir: ~/.claude-work
+    env: {ANTHROPIC_API_KEY: sk-ant-...}   # optional
+sessions:
+  - {name: shop-api, host: local, dir: ~/code/shop-api, account: work, note: payments refactor}
+  - {name: infra,    host: vm,    dir: ~/infra,         account: work, args: "--model opus"}
+notify: {on_waiting: true, on_done: true, sound: Glass}
+refresh: 3
+detach_key: C-q
+```
+
+</details>
+
+## Keys
+
+The console has the session list on the left. On the right are the selected session's
+details and a **preview**. The preview shows the session's live screen, exactly as Claude draws
+it (the same view you get when typing live or attaching); stopped sessions show their last
+conversation instead. Press Enter (or click the right panel) to type straight into the
+session from the preview (slash commands, `/model` and menus all work), or `1`–`9` to pick a
+prompt option. Go full screen (`f`) only for longer work.
+
+| Key | Action |
+|---|---|
+| `Enter` / click the right panel | Type into the selected session: every key (letters, `/`, arrows, Tab, Esc, Ctrl-C, paste) goes straight to Claude, and the preview shows Claude's own UI updating as you type, including slash-command menus, `/model`, autocomplete and pickers. Starts the session first if it's stopped. `Ctrl-q` stops typing. A click on a row only selects it |
+| `f` | Full screen: Claude's own UI in this terminal (attach; starts it first if stopped). `Ctrl-q` comes back |
+| `1`–`9` | When a session needs you: pick that numbered option in its prompt |
+| `p` | Preview: switch between auto (screen while running, conversation once stopped), conversation (from Claude's transcript) and screen |
+| `s` | Start fresh in the background and stay in derot (watch it in the preview, Enter to type) |
+| `c` | Continue this session's last conversation (falls back to the folder's newest, `claude --continue`), in the background like `s` |
+| `R` | Resume: pick any past conversation of the session's folder and account (title, age, last prompt), then start it with `claude --resume` |
+| `x` `x` | Stop (press twice within 3 s) |
+| `n` | New session (form) |
+| `e` | Edit the selected session (form) |
+| `d` | Remove the selected session from derot |
+| `l` | Log in to the selected session's account (`/login`) |
+| `E` | Open the config file in `$VISUAL`/`$EDITOR`, reload on exit |
+| `u` | Run setup (install hooks) |
+| `r` | Refresh now |
+| `q` | Quit (sessions keep running) |
+
+Inside a session, `Ctrl-q` (configurable with `detach_key`) returns to derot. `Ctrl-b d`
+always works too. Coming back from a finished session marks it as seen (done → idle).
+
+## Command line
+
+```
+derot                      open the console (creates the config on first run)
+derot init                 create the config file
+derot setup [--remove]     install / remove status hooks on every host+account
+derot ls                   print a status table
+derot start NAME [-c] [-r ID] [-d]   start (-c continue last conversation, -r resume that
+                                      conversation, -d don't attach)
+derot history NAME [-n N]            list past conversations (ids for -r)
+derot attach NAME          attach, then mark seen
+derot stop NAME
+derot watch                poll + notifications only, for when the console is closed
+derot login ACCOUNT [--host H]
+derot log [-f] [-n N]       show the log, for tracing errors
+```
+
+`derot watch` gives you desktop alerts without keeping the console open, e.g. in a spare
+terminal tab or a login item.
+
+## Troubleshooting
+
+Start with the log: **`derot log`** shows the last lines of `~/.derot/derot.log`
+(`derot log -f` follows it live). It records every action, every failure with the full error
+output, and tracebacks for anything unexpected. Error toasts in the console are logged too, so
+a message that disappeared can still be read there. For even more detail, run with
+`DEROT_DEBUG=1 derot` to log every command derot runs (API keys are masked). Errors inside
+the status hook itself go to `~/.derot/hook-errors.log` on that machine.
+
+- **`claude` not found**: sessions run in your login shell, but if it still isn't found set
+  `claude:` to the full path for that host (`which claude` on that machine).
+- **Session shows "needs you: Claude hasn't started yet"**: Claude is on a screen that comes
+  before the session, such as "trust this folder?" or a new account's login. Press Enter (or
+  click the right panel) and answer it. If nothing is there, press `u` to reinstall the hooks.
+- **Codex session shows "needs you: Codex isn't running derot's hooks yet"**: Codex only
+  runs hooks you've approved. Press Enter on the session (or click the right panel), type
+  `/hooks`, and trust derot's hooks (`t`). It's once per account folder. A Codex session that
+  has started but hasn't had a prompt yet shows idle: Codex reports nothing before the first
+  prompt.
+- **Codex session shows "needs you: Codex isn't logged in"**: a new Codex account folder
+  has no login yet. Press `l` (on an SSH machine it signs in with a one-time code), or press
+  Enter and answer Codex's sign-in screen. An account with `OPENAI_API_KEY` in its `env` logs
+  in with that key when a session starts (Codex ignores the variable on its own).
+- **Session stuck on idle**: status hooks are missing for that account/host. Starting a
+  session sets them up; otherwise press `u` (or run `derot setup`).
+- **Two accounts log each other out on the Mac**: Claude Code stores logins in the macOS
+  keychain, so two subscription logins can clash. Give one account an API key via its `env`
+  (`ANTHROPIC_API_KEY: ...`).
+- **Detach key conflicts** with an app you use inside sessions: change `detach_key` (e.g.
+  `C-]`). `Ctrl-b d` always works.
+- **Sessions started outside derot don't appear**: derot only tracks sessions it starts.
+  Add them with `n`, exit the old `claude`, then press `c` to continue the same conversation.
+
+## Known issues
+
+See [tracking/](tracking/README.md) for everything open. The main ones:
+
+- Quitting waits silently for background work to finish (up to a minute while hooks are
+  being set up).
+- After the console quits, a session stays at the preview's size if you attach with plain
+  tmux instead of derot.
+- An SSH machine whose login shell is csh/tcsh isn't supported yet.
+- Claude Code features that need a hook derot doesn't use (for example compaction) are
+  handled from Claude Code's documentation and haven't been seen live.
+
+## Development
+
+```sh
+uv venv && uv pip install -e '.[test]'
+.venv/bin/pytest          # needs tmux; uses a fake `claude` and fake `ssh`, no VM needed
+.venv/bin/pyflakes derot tests scripts
+.venv/bin/python scripts/screenshots.py   # regenerate docs/screenshots from demo data
+```
+
+Releases are published to PyPI from GitHub Actions; see [RELEASING.md](RELEASING.md).
+
+## License
+
+[MIT](LICENSE).
+
+derot is an independent project. It is not affiliated with, endorsed by or sponsored by
+Anthropic or OpenAI. Claude and Claude Code are trademarks of Anthropic; Codex and OpenAI are
+trademarks of OpenAI.

derot-0.1.0/README.md

@@ -0,0 +1,241 @@
+# derot
+
+[![tests](https://github.com/rootonchair/derot/actions/workflows/tests.yml/badge.svg)](https://github.com/rootonchair/derot/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Stop coding-agent sessions rotting in forgotten terminals.** derot is one terminal console
+for every **Claude Code** and **Codex** session you run: across **projects**, **accounts** and
+**machines** (this computer plus any machine you can SSH into), in one list.
+See which sessions need you, watch the agent work, and type into any of them without leaving
+the console.
+
+![derot: a session needs approval, its live screen on the right](docs/screenshots/overview.svg)
+
+## Features
+
+**Every session at a glance.** Sessions that need you (a permission prompt or a question
+with options) sort to the top, then finished ones, then the ones still working. The summary
+bar counts them, and you get a desktop notification when a session needs you.
+
+**Watch the agent work.** The right-hand panel shows the selected session's details and
+its live screen, exactly as Claude Code or Codex draws it, for local and SSH sessions alike.
+
+![a session working on a remote GPU machine](docs/screenshots/working.svg)
+
+**Type into any session from the console.** Press Enter or click the right panel and every
+key goes straight to Claude: slash commands, `/model`, menus, autocomplete, Esc, paste. Press
+`1`–`9` on the list to answer a prompt in one keystroke, or `f` for Claude's own full-screen
+UI. `Ctrl-q` always brings you back.
+
+![typing into a session: Claude's slash-command menu in the preview](docs/screenshots/typing.svg)
+
+**Pick up old conversations.** `R` lists a session's past conversations with their titles,
+age and last prompt, and resumes the one you pick. `c` continues the session's own last
+conversation.
+
+![the resume picker](docs/screenshots/resume.svg)
+
+**No YAML required.** Add sessions, machines and accounts from forms. The project folder
+field lists matching folders as you type, on the chosen machine (over SSH for remote ones),
+and the SSH target field lists hosts from your `~/.ssh/config` and `known_hosts`.
+
+![new session form with folder suggestions from an SSH machine](docs/screenshots/new-session.svg)
+
+![add machine form with SSH targets](docs/screenshots/add-machine.svg)
+
+**Claude Code and Codex side by side.** Each account belongs to an agent, so Claude Code
+and OpenAI Codex sessions share one list, with the same status, preview, typing and resume.
+
+![a Codex session working next to Claude Code sessions](docs/screenshots/codex.svg)
+
+**Sessions outlive the console.** Every session runs in tmux, so it keeps going when you
+quit derot, close the laptop lid or lose the SSH connection.
+
+## How it works
+
+- **tmux**: each session is a tmux session `cc-<name>` on a private tmux server
+  (`tmux -L derot`), so it survives detaching and never touches your own tmux setup.
+- **SSH**: remote hosts are reached with plain `ssh` (shared ControlMaster connection, one
+  call per host per refresh). Nothing runs on the VM besides tmux, python3 and the agent.
+- **Hooks**: `derot setup` installs a tiny stdlib-only script, `~/.derot/hook.py`, and
+  registers it as a Claude Code or Codex hook (both agents have the same hook events). It writes `~/.derot/state/<name>.json` on each event
+  (prompt submitted, tool use, permission prompt, stop), so status is accurate without screen
+  scraping.
+- **Accounts**: each account is an agent's config folder, with its own login and settings:
+  a Claude Code folder passed via `CLAUDE_CONFIG_DIR`, or a Codex folder passed via
+  `CODEX_HOME`. For Codex, setup registers the same hook in that folder's `hooks.json`.
+
+## Install
+
+Requirements: Python 3.9+, [tmux](https://github.com/tmux/tmux), and
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or
+[Codex](https://developers.openai.com/codex) on every machine you use.
+Developed and used on macOS; the Linux code paths (tmux, `notify-send` notifications) are
+covered by CI but haven't seen much real use yet.
+
+```sh
+pipx install git+https://github.com/rootonchair/derot     # or: uv tool install git+https://github.com/rootonchair/derot
+```
+
+On macOS, `brew install tmux pipx` first. Each SSH machine needs `tmux`, `python3`, the
+agent(s) you use there, and key-based SSH access (`ssh my-vm true` works without a password
+prompt).
+
+## Setup
+
+1. Run `derot`. On first run it creates `~/.config/derot/config.yaml` (override with
+   `DEROT_CONFIG`) and opens the console.
+2. Press `n` to add a session: pick a machine, a project folder (matching folders are listed
+   as you type) and a Claude account. Choose **+ add a machine (SSH)…** or **+ add an account…** in the dropdowns
+   to create those on the spot. Saving installs the status hooks for any new machine/account
+   automatically, and offers to log in to a new account right away.
+3. Press `Enter` on a session to start it and type into it from the right panel; `Ctrl-q`
+   stops typing. `f` opens Claude's own full-screen UI instead.
+
+No YAML editing needed. `e` edits the selected session, `d` removes it, `l` logs in to the
+session's account (Claude Code opens so you can `/login`; for Codex it runs `codex login`). The config file is still plain YAML if you
+prefer it (`E` opens it in `$EDITOR`); saving from the console rewrites it without comments
+and keeps your original as `config.yaml.bak`.
+
+A VM needs tmux, python3, Claude Code and/or Codex, and key-based SSH (`ssh my-vm true`
+works without a password prompt). From the command line, the same setup is `derot login ACCOUNT [--host H]`
+and `derot setup`.
+
+<details><summary>Config file reference</summary>
+
+```yaml
+hosts:
+  vm:
+    ssh: user@my-vm            # anything `ssh` accepts, incl. ~/.ssh/config aliases
+    claude: claude             # optional: command/full path for Claude Code there
+    codex: codex               # optional: command/full path for Codex there
+accounts:
+  personal: {config_dir: ~/.claude}
+  openai: {agent: codex, config_dir: ~/.codex}   # agent: claude (default) or codex
+  work:
+    config_dir: ~/.claude-work
+    env: {ANTHROPIC_API_KEY: sk-ant-...}   # optional
+sessions:
+  - {name: shop-api, host: local, dir: ~/code/shop-api, account: work, note: payments refactor}
+  - {name: infra,    host: vm,    dir: ~/infra,         account: work, args: "--model opus"}
+notify: {on_waiting: true, on_done: true, sound: Glass}
+refresh: 3
+detach_key: C-q
+```
+
+</details>
+
+## Keys
+
+The console has the session list on the left. On the right are the selected session's
+details and a **preview**. The preview shows the session's live screen, exactly as Claude draws
+it (the same view you get when typing live or attaching); stopped sessions show their last
+conversation instead. Press Enter (or click the right panel) to type straight into the
+session from the preview (slash commands, `/model` and menus all work), or `1`–`9` to pick a
+prompt option. Go full screen (`f`) only for longer work.
+
+| Key | Action |
+|---|---|
+| `Enter` / click the right panel | Type into the selected session: every key (letters, `/`, arrows, Tab, Esc, Ctrl-C, paste) goes straight to Claude, and the preview shows Claude's own UI updating as you type, including slash-command menus, `/model`, autocomplete and pickers. Starts the session first if it's stopped. `Ctrl-q` stops typing. A click on a row only selects it |
+| `f` | Full screen: Claude's own UI in this terminal (attach; starts it first if stopped). `Ctrl-q` comes back |
+| `1`–`9` | When a session needs you: pick that numbered option in its prompt |
+| `p` | Preview: switch between auto (screen while running, conversation once stopped), conversation (from Claude's transcript) and screen |
+| `s` | Start fresh in the background and stay in derot (watch it in the preview, Enter to type) |
+| `c` | Continue this session's last conversation (falls back to the folder's newest, `claude --continue`), in the background like `s` |
+| `R` | Resume: pick any past conversation of the session's folder and account (title, age, last prompt), then start it with `claude --resume` |
+| `x` `x` | Stop (press twice within 3 s) |
+| `n` | New session (form) |
+| `e` | Edit the selected session (form) |
+| `d` | Remove the selected session from derot |
+| `l` | Log in to the selected session's account (`/login`) |
+| `E` | Open the config file in `$VISUAL`/`$EDITOR`, reload on exit |
+| `u` | Run setup (install hooks) |
+| `r` | Refresh now |
+| `q` | Quit (sessions keep running) |
+
+Inside a session, `Ctrl-q` (configurable with `detach_key`) returns to derot. `Ctrl-b d`
+always works too. Coming back from a finished session marks it as seen (done → idle).
+
+## Command line
+
+```
+derot                      open the console (creates the config on first run)
+derot init                 create the config file
+derot setup [--remove]     install / remove status hooks on every host+account
+derot ls                   print a status table
+derot start NAME [-c] [-r ID] [-d]   start (-c continue last conversation, -r resume that
+                                      conversation, -d don't attach)
+derot history NAME [-n N]            list past conversations (ids for -r)
+derot attach NAME          attach, then mark seen
+derot stop NAME
+derot watch                poll + notifications only, for when the console is closed
+derot login ACCOUNT [--host H]
+derot log [-f] [-n N]       show the log, for tracing errors
+```
+
+`derot watch` gives you desktop alerts without keeping the console open, e.g. in a spare
+terminal tab or a login item.
+
+## Troubleshooting
+
+Start with the log: **`derot log`** shows the last lines of `~/.derot/derot.log`
+(`derot log -f` follows it live). It records every action, every failure with the full error
+output, and tracebacks for anything unexpected. Error toasts in the console are logged too, so
+a message that disappeared can still be read there. For even more detail, run with
+`DEROT_DEBUG=1 derot` to log every command derot runs (API keys are masked). Errors inside
+the status hook itself go to `~/.derot/hook-errors.log` on that machine.
+
+- **`claude` not found**: sessions run in your login shell, but if it still isn't found set
+  `claude:` to the full path for that host (`which claude` on that machine).
+- **Session shows "needs you: Claude hasn't started yet"**: Claude is on a screen that comes
+  before the session, such as "trust this folder?" or a new account's login. Press Enter (or
+  click the right panel) and answer it. If nothing is there, press `u` to reinstall the hooks.
+- **Codex session shows "needs you: Codex isn't running derot's hooks yet"**: Codex only
+  runs hooks you've approved. Press Enter on the session (or click the right panel), type
+  `/hooks`, and trust derot's hooks (`t`). It's once per account folder. A Codex session that
+  has started but hasn't had a prompt yet shows idle: Codex reports nothing before the first
+  prompt.
+- **Codex session shows "needs you: Codex isn't logged in"**: a new Codex account folder
+  has no login yet. Press `l` (on an SSH machine it signs in with a one-time code), or press
+  Enter and answer Codex's sign-in screen. An account with `OPENAI_API_KEY` in its `env` logs
+  in with that key when a session starts (Codex ignores the variable on its own).
+- **Session stuck on idle**: status hooks are missing for that account/host. Starting a
+  session sets them up; otherwise press `u` (or run `derot setup`).
+- **Two accounts log each other out on the Mac**: Claude Code stores logins in the macOS
+  keychain, so two subscription logins can clash. Give one account an API key via its `env`
+  (`ANTHROPIC_API_KEY: ...`).
+- **Detach key conflicts** with an app you use inside sessions: change `detach_key` (e.g.
+  `C-]`). `Ctrl-b d` always works.
+- **Sessions started outside derot don't appear**: derot only tracks sessions it starts.
+  Add them with `n`, exit the old `claude`, then press `c` to continue the same conversation.
+
+## Known issues
+
+See [tracking/](tracking/README.md) for everything open. The main ones:
+
+- Quitting waits silently for background work to finish (up to a minute while hooks are
+  being set up).
+- After the console quits, a session stays at the preview's size if you attach with plain
+  tmux instead of derot.
+- An SSH machine whose login shell is csh/tcsh isn't supported yet.
+- Claude Code features that need a hook derot doesn't use (for example compaction) are
+  handled from Claude Code's documentation and haven't been seen live.
+
+## Development
+
+```sh
+uv venv && uv pip install -e '.[test]'
+.venv/bin/pytest          # needs tmux; uses a fake `claude` and fake `ssh`, no VM needed
+.venv/bin/pyflakes derot tests scripts
+.venv/bin/python scripts/screenshots.py   # regenerate docs/screenshots from demo data
+```
+
+Releases are published to PyPI from GitHub Actions; see [RELEASING.md](RELEASING.md).
+
+## License
+
+[MIT](LICENSE).
+
+derot is an independent project. It is not affiliated with, endorsed by or sponsored by
+Anthropic or OpenAI. Claude and Claude Code are trademarks of Anthropic; Codex and OpenAI are
+trademarks of OpenAI.

derot-0.1.0/derot/__init__.py

@@ -0,0 +1,3 @@
+"""derot: one console for every Claude Code and Codex session."""
+
+__version__ = "0.1.0"

derot-0.1.0/derot/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())