bitacora 1.0.0__tar.gz

bitacora-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+*.spec
+# local state from the pre-1.0 script
+.codex-watch-cache.json

bitacora-1.0.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0 (2026-10-07)
+
+First public release.
+
+- Live dashboard for coding agents working in the background, with providers for Codex and Claude Code.
+- Every session with its status, an activity feed (commands, edits, messages, thinking time) and tabs for messages, files, log, result and details.
+- Matches live processes to their sessions by id, or by working directory and start time, including forked Claude Code sessions.
+- Finds a run's log from the parent shell's redirect and remembers result and log paths after the run ends.
+- Codex quota, tokens and context per session.
+- Views (background runs, everything, interactive, live only) and custom views in `config.toml`.
+- Home and setup screen with live counts per view, language, history window, notifications and theme.
+- Notifications when a run finishes, stops or asks a question.
+- Kill with confirmation, open result or log, copy the resume command.
+- English and Spanish interface.
+- `--demo` mode with generated sessions, also used by the tests and the README screenshots.

bitacora-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baltazar Andersson
+
+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.

bitacora-1.0.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: bitacora
+Version: 1.0.0
+Summary: Live dashboard for coding agents (Codex, Claude Code) working in the background.
+Project-URL: Repository, https://github.com/baltazarandersson/bitacora
+Project-URL: Issues, https://github.com/baltazarandersson/bitacora/issues
+Project-URL: Changelog, https://github.com/baltazarandersson/bitacora/blob/main/CHANGELOG.md
+Author: Baltazar Andersson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,codex,monitor,textual,tui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: psutil>=5.9
+Requires-Dist: textual>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Bitácora
+
+**English** · [Español](README.es.md)
+
+A live dashboard for coding agents working in the background. It supports Codex and Claude Code today.
+
+![Bitácora showing two runs at work, one waiting for an answer and the rest of the day's sessions](docs/screenshot-en.svg)
+
+## Why
+
+When you hand work to agents in the background (a `codex exec` in another terminal, a `claude -p` from a script, an orchestrator that launches five runs at once), each one writes its progress to a file you never open. You find out how it went when it ends, or when you remember to look.
+
+Bitácora reads those files while they grow. It pairs every agent process with its session and shows what each run is doing, which files it touched, how much context it has left and whether it is waiting for you. It is not a launcher and not a history search tool. It is the panel you keep open while your agents work.
+
+## What it shows
+
+- Every session with its status: running, waiting for an answer, your turn, done, aborted or cut off.
+- An activity feed per session: commands with their exit codes, file edits with lines added and removed, messages, and how long the agent thought before each step.
+- Tabs for messages, touched files, the run's log, its result file and the full session details.
+- Tokens, context used and, for Codex, how much of your 5-hour and weekly quota is gone.
+- A notification when a run finishes, stops or asks you something.
+- Actions on the selected run: kill it (it asks first), open its result or log, copy the command that resumes it.
+
+## Install
+
+```bash
+uvx bitacora
+```
+
+Or install it for good with `pipx install bitacora` or `uv tool install bitacora`. You need Python 3.11 or newer.
+
+On Windows you can also download `bitacora.exe` from the [latest release](https://github.com/baltazarandersson/bitacora/releases/latest) and run it without Python. It is not code-signed, so SmartScreen will warn you the first time.
+
+To try it without any agent installed:
+
+```bash
+uvx bitacora --demo
+```
+
+## Use
+
+```bash
+bitacora                      # live sessions plus the last 24 hours
+bitacora --view background    # start in a view, skipping the setup screen
+bitacora --live               # live sessions only
+bitacora --hours 72           # a longer history window
+bitacora --lang es            # Spanish interface
+```
+
+The first time you open it, Bitácora shows its home screen. Each view there comes with the number of sessions it would show from your own machine, so you can tell at a glance what you are choosing. You can come back to that screen anytime with `s` to change the view, language, history window, notifications or theme. On short terminals the header folds into a single line by itself; `h` brings it back.
+
+![The home screen: a lighthouse sweeping its beam over falling code, the views with live counts and the settings](docs/home-en.svg)
+
+| Key | Action |
+| --- | --- |
+| `↑` `↓` | Move through sessions |
+| `Enter` / `Esc` | Go into the detail pane / back to the list |
+| `1`–`6` | Activity, Messages, Files, Log, Result, Info |
+| `PgUp` `PgDn`, `Shift+↑↓` | Scroll the detail pane from anywhere |
+| `v` | Full detail: command output, diffs, complete prompts |
+| `a` | Live sessions only |
+| `f` | Pause or resume auto-scroll |
+| `s` | Home: views and preferences |
+| `h` | Fold or unfold the header (or click the `▲ bitácora` strip) |
+| `Ctrl+P` | Command palette: switch view or language, fold the header, toggle filters |
+| `k` | Kill the selected run and its children (asks first) |
+| `o` / `l` | Open the result file / the log |
+| `c` | Copy the command that resumes the session |
+| `t` | Next theme |
+| `q` | Quit |
+
+### Views
+
+| View | Shows |
+| --- | --- |
+| Background runs | `codex exec`, `claude -p` and SDK runs |
+| Everything | Every session from every agent |
+| Interactive | Desktop apps, IDEs and terminal chats |
+| Live only | Whatever is running right now |
+
+You can add your own in `config.toml`. `bitacora --paths` prints where that file lives.
+
+```toml
+lang = "en"          # en, es, or leave it out to follow the system
+hours = 24           # history window
+notify = true        # toast and bell when a run finishes, stops or asks
+
+[views.codex-bg]
+name = "Codex in the background"
+providers = ["codex"]          # codex, claude
+kind = "background"            # background, interactive or all
+live_only = false
+```
+
+What you save in the setup screen takes precedence over `config.toml`, and command line flags take precedence over both.
+
+## How it works
+
+Bitácora only reads files the agents already write.
+
+- **Codex**: rollouts in `~/.codex/sessions` (or `$CODEX_HOME`), thread names from `session_index.jsonl`, and the `codex exec` / `codex` processes with their flags (`-m`, `-c`, `-C`, `-s`, `-o`, `resume <id>`).
+- **Claude Code**: transcripts in `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR`) and the `claude` processes with `--resume`, `--session-id`, `--model`, `-p`.
+
+A live process is matched to its session by id when the command line has one, and otherwise by working directory and start time. The log comes from a `> run.log` redirect in the parent shell's command line. Bitácora remembers each session's label, result and log paths in its own state file, so a finished run still shows them.
+
+## Privacy
+
+Everything stays on your machine. Bitácora makes no network requests and never writes to the agents' files. The only thing it can do to an agent is kill it, and only after you confirm. Its state file holds session labels and file paths; `bitacora --paths` shows where.
+
+## Limits
+
+- Neither format is documented, and both change between versions. This release was tested with Codex CLI 0.161 and Claude Code 2.1.
+- Windows is where it gets the most use. Linux and macOS pass the test suite in CI, but have seen less real use.
+- Reasoning is stored encrypted or not at all, so the activity feed shows how long the agent thought rather than what it thought (Codex includes summaries if `model_reasoning_summary` is on).
+- Claude Code does not record its context window, so for Claude sessions Bitácora shows context in tokens instead of a percentage.
+- Subagent sessions are not grouped under their parent yet.
+
+## Development
+
+```bash
+git clone https://github.com/baltazarandersson/bitacora
+cd bitacora
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # .venv\Scripts\pip on Windows
+pytest
+ruff check .
+python -m bitacora --demo
+python scripts/screenshot.py en    # regenerates docs/*.svg from the demo
+```
+
+Adding an agent means writing a provider in `bitacora/providers/`: where its sessions live, how its processes look and how to turn its records into events. The demo generator in `bitacora/demo.py` doubles as the test fixture.
+
+## License
+
+MIT. Bitácora is an independent project, not affiliated with OpenAI or Anthropic.

bitacora-1.0.0/README.es.md

@@ -0,0 +1,134 @@
+# Bitácora
+
+[English](README.md) · **Español**
+
+Un panel en vivo para los agentes de código que trabajan en segundo plano. Hoy funciona con Codex y Claude Code.
+
+![Bitácora con dos corridas trabajando, una esperando respuesta y el resto de las sesiones del día](docs/screenshot-es.svg)
+
+## Por qué
+
+Cuando le delegas trabajo a agentes en segundo plano (un `codex exec` en otra terminal, un `claude -p` desde un script, un orquestador que lanza cinco corridas a la vez), cada uno va dejando su progreso en un archivo que nunca abres. Te enteras de cómo fue cuando termina, o cuando te acuerdas de mirar.
+
+Bitácora lee esos archivos mientras crecen. Empareja cada proceso con su sesión y muestra qué está haciendo cada corrida, qué archivos tocó, cuánto contexto le queda y si está esperando algo de ti. No lanza agentes ni busca en tu historial: es el panel que dejas abierto mientras tus agentes trabajan.
+
+## Qué muestra
+
+- Cada sesión con su estado: corriendo, esperando respuesta, te toca, terminada, abortada o cortada.
+- La actividad de cada sesión: comandos con su código de salida, archivos editados con líneas agregadas y quitadas, mensajes, y cuánto pensó el agente antes de cada paso.
+- Pestañas para los mensajes, los archivos tocados, el log de la corrida, su archivo de resultado y todos los datos de la sesión.
+- Tokens, contexto usado y, en Codex, cuánto llevas gastado de la cuota de 5 horas y de la semanal.
+- Un aviso cuando una corrida termina, se corta o te pregunta algo.
+- Acciones sobre la corrida seleccionada: matarla (te pide confirmación), abrir su resultado o su log, copiar el comando que la retoma.
+
+## Instalación
+
+```bash
+uvx bitacora
+```
+
+Si prefieres dejarlo instalado: `pipx install bitacora` o `uv tool install bitacora`. Necesitas Python 3.11 o más nuevo.
+
+En Windows también puedes descargar `bitacora.exe` desde la [última release](https://github.com/baltazarandersson/bitacora/releases/latest) y usarlo sin Python. No está firmado, así que SmartScreen te va a avisar la primera vez.
+
+Para probarlo sin tener ningún agente instalado:
+
+```bash
+uvx bitacora --demo
+```
+
+## Uso
+
+```bash
+bitacora                      # sesiones vivas y las últimas 24 horas
+bitacora --view background    # arranca en una vista y saltea la pantalla de inicio
+bitacora --live               # solo sesiones vivas
+bitacora --hours 72           # una ventana de historial más larga
+bitacora --lang en            # interfaz en inglés
+```
+
+La primera vez, Bitácora abre su pantalla de inicio. Cada vista aparece con la cantidad de sesiones que mostraría con los datos de tu propia máquina, así sabes qué estás eligiendo antes de elegirlo. Puedes volver a esa pantalla cuando quieras con `s` para cambiar la vista, el idioma, la ventana de historial, los avisos o el tema. En terminales bajas la cabecera se pliega sola en una línea; `h` la despliega.
+
+![La pantalla de inicio: un faro que barre con su luz sobre código que cae, las vistas con sus conteos y la configuración](docs/home-es.svg)
+
+| Tecla | Acción |
+| --- | --- |
+| `↑` `↓` | Moverse entre sesiones |
+| `Enter` / `Esc` | Entrar al panel de detalle / volver a la lista |
+| `1`–`6` | Actividad, Mensajes, Archivos, Log, Resultado, Info |
+| `PgUp` `PgDn`, `Shift+↑↓` | Desplazar el detalle desde cualquier lado |
+| `v` | Detalle completo: salida de comandos, diffs, prompts enteros |
+| `a` | Solo sesiones vivas |
+| `f` | Pausar o reanudar el auto-scroll |
+| `s` | Inicio: vistas y preferencias |
+| `h` | Plegar o desplegar la cabecera (o un clic en la franja `▲ bitácora`) |
+| `Ctrl+P` | Paleta de comandos: cambiar de vista o idioma, plegar la cabecera, alternar filtros |
+| `k` | Matar la corrida seleccionada y sus hijos (pide confirmación) |
+| `o` / `l` | Abrir el archivo de resultado / el log |
+| `c` | Copiar el comando que retoma la sesión |
+| `t` | Siguiente tema |
+| `q` | Salir |
+
+### Vistas
+
+| Vista | Muestra |
+| --- | --- |
+| En segundo plano | `codex exec`, `claude -p` y corridas del SDK |
+| Todo | Todas las sesiones de todos los agentes |
+| Interactivas | Apps de escritorio, IDEs y chats en terminal |
+| Solo vivas | Lo que está corriendo ahora |
+
+Puedes sumar las tuyas en `config.toml`. `bitacora --paths` te dice dónde está ese archivo.
+
+```toml
+lang = "es"          # en, es, o no lo pongas para seguir al sistema
+hours = 24           # ventana de historial
+notify = true        # aviso y campana cuando una corrida termina, se corta o pregunta
+
+[views.codex-bg]
+name = "Codex en segundo plano"
+providers = ["codex"]          # codex, claude
+kind = "background"            # background, interactive o all
+live_only = false
+```
+
+Lo que guardas en la pantalla de configuración tiene prioridad sobre `config.toml`, y los flags de la línea de comandos tienen prioridad sobre los dos.
+
+## Cómo funciona
+
+Bitácora solo lee archivos que los agentes ya escriben.
+
+- **Codex**: los rollouts en `~/.codex/sessions` (o `$CODEX_HOME`), los nombres de los threads en `session_index.jsonl`, y los procesos `codex exec` / `codex` con sus flags (`-m`, `-c`, `-C`, `-s`, `-o`, `resume <id>`).
+- **Claude Code**: las transcripciones en `~/.claude/projects` (o `$CLAUDE_CONFIG_DIR`) y los procesos `claude` con `--resume`, `--session-id`, `--model`, `-p`.
+
+Cada proceso vivo se empareja con su sesión por id cuando la línea de comandos lo trae, y si no, por carpeta de trabajo y hora de inicio. El log sale de una redirección `> run.log` en la línea de comandos del shell padre. Bitácora guarda el nombre, el resultado y el log de cada sesión en su propio archivo de estado, así una corrida terminada los sigue mostrando.
+
+## Privacidad
+
+Todo queda en tu máquina. Bitácora no hace pedidos a la red y nunca escribe en los archivos de los agentes. Lo único que le puede hacer a un agente es matarlo, y solo después de que confirmes. Su archivo de estado guarda nombres de sesiones y rutas de archivos; `bitacora --paths` te muestra dónde.
+
+## Límites
+
+- Ninguno de los dos formatos está documentado, y los dos cambian entre versiones. Esta versión se probó con Codex CLI 0.161 y Claude Code 2.1.
+- Donde más se usa es en Windows. En Linux y macOS pasa los tests en CI, pero tiene menos uso real.
+- El razonamiento se guarda cifrado o no se guarda, así que la actividad muestra cuánto pensó el agente y no qué pensó (Codex incluye resúmenes si `model_reasoning_summary` está activo).
+- Claude Code no registra su ventana de contexto, así que en sus sesiones Bitácora muestra el contexto en tokens y no en porcentaje.
+- Las sesiones de subagentes todavía no se agrupan bajo su sesión madre.
+
+## Desarrollo
+
+```bash
+git clone https://github.com/baltazarandersson/bitacora
+cd bitacora
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # .venv\Scripts\pip en Windows
+pytest
+ruff check .
+python -m bitacora --demo
+python scripts/screenshot.py es    # regenera docs/*.svg a partir de la demo
+```
+
+Sumar un agente es escribir un provider en `bitacora/providers/`: dónde guarda sus sesiones, cómo se ven sus procesos y cómo convertir sus registros en eventos. El generador de la demo en `bitacora/demo.py` también sirve como fixture de los tests.
+
+## Licencia
+
+MIT. Bitácora es un proyecto independiente, sin relación con OpenAI ni Anthropic.

bitacora-1.0.0/README.md

@@ -0,0 +1,134 @@
+# Bitácora
+
+**English** · [Español](README.es.md)
+
+A live dashboard for coding agents working in the background. It supports Codex and Claude Code today.
+
+![Bitácora showing two runs at work, one waiting for an answer and the rest of the day's sessions](docs/screenshot-en.svg)
+
+## Why
+
+When you hand work to agents in the background (a `codex exec` in another terminal, a `claude -p` from a script, an orchestrator that launches five runs at once), each one writes its progress to a file you never open. You find out how it went when it ends, or when you remember to look.
+
+Bitácora reads those files while they grow. It pairs every agent process with its session and shows what each run is doing, which files it touched, how much context it has left and whether it is waiting for you. It is not a launcher and not a history search tool. It is the panel you keep open while your agents work.
+
+## What it shows
+
+- Every session with its status: running, waiting for an answer, your turn, done, aborted or cut off.
+- An activity feed per session: commands with their exit codes, file edits with lines added and removed, messages, and how long the agent thought before each step.
+- Tabs for messages, touched files, the run's log, its result file and the full session details.
+- Tokens, context used and, for Codex, how much of your 5-hour and weekly quota is gone.
+- A notification when a run finishes, stops or asks you something.
+- Actions on the selected run: kill it (it asks first), open its result or log, copy the command that resumes it.
+
+## Install
+
+```bash
+uvx bitacora
+```
+
+Or install it for good with `pipx install bitacora` or `uv tool install bitacora`. You need Python 3.11 or newer.
+
+On Windows you can also download `bitacora.exe` from the [latest release](https://github.com/baltazarandersson/bitacora/releases/latest) and run it without Python. It is not code-signed, so SmartScreen will warn you the first time.
+
+To try it without any agent installed:
+
+```bash
+uvx bitacora --demo
+```
+
+## Use
+
+```bash
+bitacora                      # live sessions plus the last 24 hours
+bitacora --view background    # start in a view, skipping the setup screen
+bitacora --live               # live sessions only
+bitacora --hours 72           # a longer history window
+bitacora --lang es            # Spanish interface
+```
+
+The first time you open it, Bitácora shows its home screen. Each view there comes with the number of sessions it would show from your own machine, so you can tell at a glance what you are choosing. You can come back to that screen anytime with `s` to change the view, language, history window, notifications or theme. On short terminals the header folds into a single line by itself; `h` brings it back.
+
+![The home screen: a lighthouse sweeping its beam over falling code, the views with live counts and the settings](docs/home-en.svg)
+
+| Key | Action |
+| --- | --- |
+| `↑` `↓` | Move through sessions |
+| `Enter` / `Esc` | Go into the detail pane / back to the list |
+| `1`–`6` | Activity, Messages, Files, Log, Result, Info |
+| `PgUp` `PgDn`, `Shift+↑↓` | Scroll the detail pane from anywhere |
+| `v` | Full detail: command output, diffs, complete prompts |
+| `a` | Live sessions only |
+| `f` | Pause or resume auto-scroll |
+| `s` | Home: views and preferences |
+| `h` | Fold or unfold the header (or click the `▲ bitácora` strip) |
+| `Ctrl+P` | Command palette: switch view or language, fold the header, toggle filters |
+| `k` | Kill the selected run and its children (asks first) |
+| `o` / `l` | Open the result file / the log |
+| `c` | Copy the command that resumes the session |
+| `t` | Next theme |
+| `q` | Quit |
+
+### Views
+
+| View | Shows |
+| --- | --- |
+| Background runs | `codex exec`, `claude -p` and SDK runs |
+| Everything | Every session from every agent |
+| Interactive | Desktop apps, IDEs and terminal chats |
+| Live only | Whatever is running right now |
+
+You can add your own in `config.toml`. `bitacora --paths` prints where that file lives.
+
+```toml
+lang = "en"          # en, es, or leave it out to follow the system
+hours = 24           # history window
+notify = true        # toast and bell when a run finishes, stops or asks
+
+[views.codex-bg]
+name = "Codex in the background"
+providers = ["codex"]          # codex, claude
+kind = "background"            # background, interactive or all
+live_only = false
+```
+
+What you save in the setup screen takes precedence over `config.toml`, and command line flags take precedence over both.
+
+## How it works
+
+Bitácora only reads files the agents already write.
+
+- **Codex**: rollouts in `~/.codex/sessions` (or `$CODEX_HOME`), thread names from `session_index.jsonl`, and the `codex exec` / `codex` processes with their flags (`-m`, `-c`, `-C`, `-s`, `-o`, `resume <id>`).
+- **Claude Code**: transcripts in `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR`) and the `claude` processes with `--resume`, `--session-id`, `--model`, `-p`.
+
+A live process is matched to its session by id when the command line has one, and otherwise by working directory and start time. The log comes from a `> run.log` redirect in the parent shell's command line. Bitácora remembers each session's label, result and log paths in its own state file, so a finished run still shows them.
+
+## Privacy
+
+Everything stays on your machine. Bitácora makes no network requests and never writes to the agents' files. The only thing it can do to an agent is kill it, and only after you confirm. Its state file holds session labels and file paths; `bitacora --paths` shows where.
+
+## Limits
+
+- Neither format is documented, and both change between versions. This release was tested with Codex CLI 0.161 and Claude Code 2.1.
+- Windows is where it gets the most use. Linux and macOS pass the test suite in CI, but have seen less real use.
+- Reasoning is stored encrypted or not at all, so the activity feed shows how long the agent thought rather than what it thought (Codex includes summaries if `model_reasoning_summary` is on).
+- Claude Code does not record its context window, so for Claude sessions Bitácora shows context in tokens instead of a percentage.
+- Subagent sessions are not grouped under their parent yet.
+
+## Development
+
+```bash
+git clone https://github.com/baltazarandersson/bitacora
+cd bitacora
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # .venv\Scripts\pip on Windows
+pytest
+ruff check .
+python -m bitacora --demo
+python scripts/screenshot.py en    # regenerates docs/*.svg from the demo
+```
+
+Adding an agent means writing a provider in `bitacora/providers/`: where its sessions live, how its processes look and how to turn its records into events. The demo generator in `bitacora/demo.py` doubles as the test fixture.
+
+## License
+
+MIT. Bitácora is an independent project, not affiliated with OpenAI or Anthropic.

bitacora-1.0.0/bitacora/__init__.py

@@ -0,0 +1,3 @@
+"""Bitácora: a live dashboard for coding agents working in the background."""
+
+__version__ = "1.0.0"

bitacora-1.0.0/bitacora/__main__.py

@@ -0,0 +1,3 @@
+from bitacora.cli import main
+
+main()

bitacora-1.0.0/bitacora/cli.py

@@ -0,0 +1,78 @@
+"""Command line entry point."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from bitacora import __version__, i18n
+from bitacora.store import State, config_path, load_config, state_path
+from bitacora.views import BUILTIN
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="bitacora",
+        description="Live dashboard for coding agents (Codex, Claude Code) working in the background.")
+    ap.add_argument("--view", help="start in this view: " + ", ".join(v.id for v in BUILTIN)
+                    + " or one from config.toml (skips the first-run picker)")
+    ap.add_argument("--live", action="store_true", help="show live sessions only")
+    ap.add_argument("--hours", type=float, help="history window in hours (default 24)")
+    ap.add_argument("--lang", choices=i18n.LANGS, help="interface language (default: system)")
+    ap.add_argument("--demo", action="store_true", help="run on generated sample sessions")
+    ap.add_argument("--paths", action="store_true", help="print where config and state live, and exit")
+    ap.add_argument("--version", action="version", version=f"bitacora {__version__}")
+    return ap
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    if args.paths:
+        print(json.dumps({"config": str(config_path()), "state": str(state_path())}, indent=1))
+        return
+
+    animator = None
+    if args.demo:
+        from bitacora import demo
+        root = Path(tempfile.mkdtemp(prefix="bitacora-demo-"))
+        data = demo.generate(root)
+        os.environ["CODEX_HOME"] = str(data["codex_home"])
+        os.environ["CLAUDE_CONFIG_DIR"] = str(data["claude_home"])
+        os.environ["BITACORA_HOME"] = str(root / "home")
+        seed = State()
+        for key, entry in data["state"].items():
+            seed.remember(key, entry)
+        seed.save()
+        animator = demo.Animator(data["live"])
+
+    from bitacora.providers import all_providers
+    from bitacora.ui.app import create_app
+
+    if animator:
+        animator.start()
+    view, collector = args.view, None
+    try:
+        while True:
+            # Precedence: command line, then what you saved in setup, then config.toml.
+            config, state = load_config(), State()
+            lang = args.lang or state.get("lang") or config.lang or "auto"
+            config.hours = args.hours or state.get("hours") or config.hours
+            config.notify = state.get("notify", config.notify)
+            i18n.set_lang(None if lang == "auto" else lang)
+            app = create_app(all_providers(), config, state, view=view, live_only=args.live,
+                             scan_procs=not args.demo, lang=args.lang or state.get("lang") or "auto",
+                             collector=collector)
+            if app.run() != "relaunch":
+                break
+            collector = app.collector  # keep what was already read; the new app only relabels
+            view = None  # a relaunch after setup starts in the view just saved
+    finally:
+        if animator:
+            animator.stop.set()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bitacora-1.0.0/bitacora/collector.py

@@ -0,0 +1,95 @@
+"""Joins live processes with their session files, plus recent history, across providers."""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from bitacora import procs
+from bitacora.model import ProcInfo, Run, Session
+from bitacora.providers import Provider
+from bitacora.store import State
+from bitacora.util import label_from_out, label_from_prompt
+
+
+class Collector:
+    def __init__(self, providers: list[Provider], state: State, hours: float, scan_procs: bool = True):
+        self.providers = providers
+        self.state = state
+        self.hours = hours
+        self.scan_procs = scan_procs
+        self.sessions: dict[Path, Session] = {}
+        self.pid_map: dict[tuple[str, int], Path] = {}
+        self.log_seen: dict[tuple[str, int], str | None] = {}
+        self.quotas: dict[str, dict] = {}
+
+    def _session(self, prov: Provider, path: Path) -> Session:
+        s = self.sessions.get(path)
+        if s is None:
+            s = self.sessions[path] = prov.session_cls(path)
+        s.update()
+        title = prov.title(s)
+        if title:
+            s.title = title
+        return s
+
+    def _live_run(self, prov: Provider, pi: ProcInfo, claimed: set[Path]) -> Run:
+        key = (prov.name, pi.pid)
+        path = self.pid_map.get(key)
+        if path is None or not path.exists():
+            path = prov.match(pi, claimed)
+        s = None
+        if path:
+            self.pid_map[key] = path
+            claimed.add(path)
+            s = self._session(prov, path)
+        sid = s.session_id if s else None
+        skey = f"{prov.name}:{sid}" if sid else ""
+        cached = self.state.session(skey) if skey else {}
+        out = pi.out or cached.get("out")
+        if pi.log is None:
+            # The redirect is fixed at launch and walking parent processes is slow: look once per process.
+            if key not in self.log_seen:
+                self.log_seen[key] = cached.get("log") or procs.find_log(pi.pid, out, prov.marker)
+            pi.log = self.log_seen[key]
+        label = (label_from_out(out) or (s and s.title) or cached.get("label")
+                 or (s and label_from_prompt(s.first_prompt)) or f"pid {pi.pid}")
+        if skey:
+            self.state.remember(skey, {"label": label, "out": out, "log": pi.log, "cmdline": pi.cmdline})
+        return Run(skey or f"{prov.name}:pid{pi.pid}", prov.name, s, pi, label, out, pi.log)
+
+    def collect(self) -> list[Run]:
+        snap = procs.snapshot() if self.scan_procs else []
+        runs: dict[str, Run] = {}
+        since = time.time() - self.hours * 3600
+        seen: set[Path] = set()
+        alive: set[tuple[str, int]] = set()
+        for prov in self.providers:
+            if not prov.available():
+                continue
+            claimed: set[Path] = set()
+            for pi in sorted(prov.procs(snap), key=lambda x: x.create):
+                alive.add((prov.name, pi.pid))
+                run = self._live_run(prov, pi, claimed)
+                runs[run.key] = run
+            seen |= claimed
+            for f in prov.history(since):
+                if f in claimed:
+                    continue
+                s = self._session(prov, f)
+                seen.add(f)
+                key = f"{prov.name}:{s.session_id or f}"
+                if key in runs:
+                    continue
+                cached = self.state.session(key)
+                label = (label_from_out(cached.get("out")) or s.title or cached.get("label")
+                         or label_from_prompt(s.first_prompt) or f.stem[-12:])
+                runs[key] = Run(key, prov.name, s, None, label, cached.get("out"), cached.get("log"))
+            mine = [s for p, s in self.sessions.items() if s.provider == prov.name and p in seen]
+            quota = prov.quota(mine)
+            if quota:
+                self.quotas[prov.name] = quota
+        self.pid_map = {k: v for k, v in self.pid_map.items() if k in alive}
+        self.log_seen = {k: v for k, v in self.log_seen.items() if k in alive}
+        self.sessions = {p: s for p, s in self.sessions.items() if p in seen}
+        self.state.save()
+        return sorted(runs.values(), key=lambda r: (not r.live, -(r.start or 0)))