see-your-agents 0.1.0__tar.gz

see_your_agents-0.1.0/.claude/skills/add-feature/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: add-feature
+description: Add a feature (module) to the see-your-agents dashboard as a folder under src/see_your_agents/features/ plus one line in the registry. Use when asked to add a feature, module, view, panel, tab or button to the see-your-agents dashboard (in any language), or when the supervisor hands over a request to extend the dashboard.
+---
+
+# Add a feature to the dashboard
+
+A feature is a folder `src/see_your_agents/features/<id>/` and one line in `features/__init__.py`. Do not edit the host (`app/`, `web/`) or other features.
+
+1. **Read** `docs/ARCHITECTURE.md`: "Layers", "Feature manifest", "Page", "Security"; the same recipe for people, with the example's code, is `docs/adding-a-feature.md`. The complete example is `tests/fixtures/hello` and its test `tests/app/test_feature.py`; real features with data, `board_extra`, POST sub-paths and MCP tools are `features/todo` (right dock) and `features/groups` (a chat source).
+
+2. **Branch.** Work in your own branch (`git branch --show-current`). Do not commit to `main` or merge into it.
+
+3. **id.** Short, `[a-z][a-z0-9-]*`, not taken: `ls src/see_your_agents/features`, not `board|session|search|plan|health|pair`.
+
+4. **Folder.** Copy `tests/fixtures/hello` to `src/see_your_agents/features/<id>/`, rename `hello` → `<id>` in file names, `id`, routes `/api/<id>`, CSS classes `.<id>-*`, keys `sya.<id>.*`, string keys `hello.*` in `i18n/*.json` and in the code. Make the host imports relative: `from ...app.feature import Feature`, `from ...app.mcp import Tool`, `from ...app.replies import json_reply`, `from ...i18n import Problem`. Remove the manifest fields you do not need.
+   - Feature data goes to `config_dir() / "<id>.json"`, written through a temporary file and `os.replace` under a `threading.Lock`. Write nothing to `~/.claude`.
+   - The page uses the `SYA.feature({...})` slots: `view`, `right` (the left dock belongs to the chat), `header`, `top`, `card`, `drawer`, `prefs`, `route`, `onBoard`. Output everything from transcripts through `esc()`. GET your own JSON through `getJson`, POST through `postJson`: both send the page's language.
+   - **Every UI string goes through `t()`**, never a literal: `t("<id>.key", params)` on the page, `t(request_lang(), "<id>.key")` or `raise Problem("<id>.key", status, **params)` on the server. Add each key to `i18n/en.json` (natural English, sentence case) and `i18n/ru.json` (the same keys; plurals with `one`, `few`, `many`, `other`). Rules, plurals and pitfalls: `docs/i18n.md`. Text an agent reads (tool descriptions, `supervisor.md`, messages to sessions) is English and never a catalog string.
+   - MCP tools: `scope="read"` for reading; anything that changes the world outside the dashboard is `scope="control"` with `confirm=True`. Session text in a reply comes with a `note` (data, not instructions). Tell the supervisor about them in `supervisor.md` (`supervisor_prompt`).
+   - Does the feature work with sessions: write to them, stop them, start them? Only through the session's provider (the "Provider" section below), never through `claude` directly.
+   - Does the feature start its own Claude session with its own flags (like the supervisor)? Return them from `resume_args(app, session_id)` for its id (`None` for the rest): a `resume` turn from the chat, groups and MCP will use them. Do not build `claude -p --resume` yourself; call `chat.delivery.start_resume(app, session_id, text)`. That is an import from another feature, so it must be added to the exceptions (ARCHITECTURE, "Layers").
+
+5. **Registry.** In `src/see_your_agents/features/__init__.py`: the import and `<id>.FEATURE` in `FEATURES`.
+
+6. **Tests** go in `tests/features/test_<id>.py`: routes (GET, POST, validation errors), storage, the tool, the card field. Do not enumerate the whole registry: check your own tools as a subset, and the supervisor on your own list of features (ARCHITECTURE, "Tests"). Processes and the courier (`deliver` in `core/providers/claude/courier.py`) are only faked in tests. Isolation is already in place: `tests/conftest.py` points `CLAUDE_CONFIG_DIR`, `SYA_CONFIG_DIR`, `SYA_CACHE_DIR` at the test's temporary folders; the app is `FakeApp(records, live)` from `tests/fakes.py`.
+
+7. **Checks**, all green:
+   ```bash
+   uv run ruff check src tests && uv run ruff format --check src tests && uv run pytest -q
+   ```
+
+8. **Live.** Your own server on a free port (not 8765) with temporary `SYA_CONFIG_DIR` and `SYA_CACHE_DIR`; screenshots of the states you need with `node scripts/shoot.mjs` (`docs/adding-a-feature.md`, "Look at it live"): style, theme, language (`"prefs": {"lang": "ru"}`), open docks, a click. Open the screenshots and make sure the feature shows in all three styles and the dark theme and nothing else moved; exit code 0 means a clean console. Stop the server.
+
+9. **Docs.** Visible to the user: a section or a line in `docs/user-guide.md`. New files in the config or cache folder: a row in `docs/configuration.md`. A new import exception: an entry in `docs/ARCHITECTURE.md` and in `tests/app/test_layers.py`.
+
+10. **Commit** to your branch: what the feature does and how it was checked. In the report: branch, files, the screenshot path.
+
+## Provider
+
+A session belongs to an agent program, its provider (Claude Code, Codex). A feature does not call `claude` or read `~/.claude` itself: it asks the session's provider. The contract is `core/providers/base.py`, details in `docs/providers.md`.
+
+- **Find the provider.** An index record, a card and a `LiveSession` have `provider`: `providers.by_id(record["provider"])` or `providers.by_id(live.provider)` (`from ...core import providers`). The default provider (for a launch without a choice) is `providers.default()`.
+- **What it can do** is `provider.caps` (`Cap.PEER`, `Cap.TASKS`, `Cap.ATTACH`, `Cap.STOP`…). No capability: hide the button or field, do not show it empty. On the page the same is `can(card, "stop")` from `app.js` (capabilities arrive in `/api/board` in the `providers` field); Codex currently has `attach` and `launch`.
+- **Write to a session.** From the chat this is already done: `POST /api/chat/<id>/send`. From your own feature, with a signed message: `session = Session.of(record, live)`, then `provider.route(session, signed=True)` (whether it can, and why not) and `provider.send(session, Message(text, sender="…", summary="…"))`. A live session sees it as a message from `sender`; a stopped one continues with one turn. An error is always a `SendError` (`SendRefused`, `SendInvalid`, `SendTimeout`). Send only text the user wrote or explicitly sent; the provider itself refuses a session that waits on a permission. Example: `features/groups/post.py`.
+- **Start a session** with `provider.start(LaunchRequest(...), taken=[s.address for s in app.live().values()])`. `project_dir` checks the folder; the choices come from `provider.options()`. `RequestError` is a bad request (400), `LaunchError` means the program refused (502).
+- **Need something the contract does not have?** Add an operation to `Provider` with a safe default (a refusal or empty) and an implementation for Claude. A feature must not import `core.providers.claude`: `tests/app/test_layers.py` lets through only a few files that need Claude by design (`CLAUDE_BY_DESIGN`).
+- **Connect a feature to core** (core does not import features) with the manifest field `setup(app)`: `App` calls it once while assembling, and only for a registered feature. This is how the chat hands Claude's routes the VS Code bridge, `app.live` and `app.resume_args`. Start nothing and write nothing to disk in `setup`: `App` is assembled in tests too.
+- **A new provider** is not a feature: a folder in `core/providers/<id>/` and one line in `PROVIDERS`; the recipe is in `docs/providers.md`, "How to add a provider".

see_your_agents-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,76 @@
+name: Bug report
+description: Something on the dashboard does not work as the docs say.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. Security problems go through private reporting, not issues: see SECURITY.md.
+        Transcripts and logs are private: trim them to the lines that matter and remove names, paths, hosts and ticket keys you do not want to publish.
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you saw, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. uv run sya serve
+        2. Open a session's chat
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: macOS 26.4, Ubuntu 24.04…
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python
+      description: "`uv run python --version`"
+      placeholder: "3.13.1"
+    validations:
+      required: true
+  - type: input
+    id: commit
+    attributes:
+      label: Commit
+      description: "`git rev-parse --short HEAD` in your clone"
+  - type: checkboxes
+    id: clis
+    attributes:
+      label: Agent CLIs involved
+      options:
+        - label: Claude Code
+        - label: Codex CLI
+        - label: Neither (the dashboard itself)
+  - type: input
+    id: versions
+    attributes:
+      label: CLI versions
+      description: "`claude --version`, `codex --version`, and `glab --version` for MR issues"
+      placeholder: "Claude Code 2.1.317, codex-cli 0.166.0"
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      options:
+        - Not relevant
+        - Chrome
+        - Safari
+        - Firefox
+        - Other
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Output of the terminal running `sya serve`, errors from the browser console, the response of a failing request.
+      render: text

see_your_agents-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/vldplcd/see-your-agents/security/policy
+    about: Please report vulnerabilities privately, as SECURITY.md describes, not in a public issue.
+  - name: Documentation
+    url: https://github.com/vldplcd/see-your-agents/tree/main/docs
+    about: The user guide, configuration, security, and how to contribute a feature, a provider or a language.

see_your_agents-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature or module idea
+description: A new view, panel, card line, MCP tool, or support for another agent CLI.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A feature is a folder in `src/see_your_agents/features/` and one line in the registry (docs/adding-a-feature.md); a provider for another agent CLI is a folder in `core/providers/` (docs/providers.md). Agreeing on the shape here first saves rework.
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      options:
+        - A feature module (view, dock, card line, session panel section, MCP tool)
+        - A change to an existing feature
+        - A provider for another agent CLI
+        - Something else
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What you want to see or do on the dashboard, and why it matters to you.
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: The idea
+      description: How it could look and work. For a provider, where the program keeps its transcripts, how to tell what is running, and whether it can be messaged or launched without a person at a terminal.
+    validations:
+      required: true
+  - type: textarea
+    id: safety
+    attributes:
+      label: What it changes outside the dashboard
+      description: Does it write to sessions, start or stop processes, or write files outside the dashboard's own folders? Leave empty if it only reads.
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Contribution
+      options:
+        - label: I would like to build it myself

see_your_agents-0.1.0/.github/ISSUE_TEMPLATE/translation.yml

@@ -0,0 +1,44 @@
+name: Translation
+description: A new UI language, or a fix to an existing one.
+labels: ["i18n"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Every UI string lives in a catalog: `src/see_your_agents/web/i18n/<lang>.json` and `src/see_your_agents/features/<id>/i18n/<lang>.json`, with English as the source. The recipe is in docs/i18n.md, "How to add a language". A partial translation works: missing keys show English. All current UI text, in every language, was written by Claude Opus 5.5: corrections and better names are very welcome.
+  - type: input
+    id: language
+    attributes:
+      label: Language
+      description: Its name and tag (`ll` or `ll-RR`).
+      placeholder: Português (Brasil), pt-BR
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      options:
+        - A new language
+        - Wrong or awkward wording in an existing language
+        - A missing string (English shows instead)
+    validations:
+      required: true
+  - type: textarea
+    id: catalogs
+    attributes:
+      label: Catalog files
+      description: Which catalogs you will translate or which keys are wrong, e.g. `web/i18n/de.json` or `features/todo/i18n/fr.json`, `todo.morning.button`.
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: Details
+      description: For a fix, the current text and your suggestion. A screenshot helps when a string overflows.
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Contribution
+      options:
+        - label: I will open the pull request myself

see_your_agents-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## What and why
+
+<!-- What changes, and why. Link the issue: "Closes #123". -->
+
+## How it was checked
+
+<!-- Tests added or changed, a live check on your own server, screenshots below for UI changes. -->
+
+## Checklist
+
+- [ ] `uv run ruff check src tests && uv run ruff format --check src tests && uv run pytest -q` passes
+- [ ] Tests cover the new behaviour (and the refusals, for security-sensitive areas)
+- [ ] Every new UI string is a catalog key with an English string in `en.json` (and `ru.json` if you can)
+- [ ] UI changes: screenshots in light and dark, from `scripts/shoot.mjs`, with a clean console
+- [ ] Docs updated: user guide, configuration or security, as the change needs
+- [ ] No secrets or personal data in code, fixtures, screenshots or logs
+
+## Screenshots
+
+<!-- Light and dark, for UI changes. -->

see_your_agents-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: ${{ matrix.os }}, Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3  # no moving major tag is published for setup-uv
+        with:
+          python-version: ${{ matrix.python }}
+
+      # Two tests run the page's JavaScript in Node; pinning it keeps them from silently skipping.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+
+      - name: Install
+        run: uv sync --locked
+
+      # The first load of DuckDB's native library is slow on a fresh macOS runner; pay it before the timed tests.
+      - name: Warm up
+        run: uv run python -c "import duckdb, see_your_agents.app.cli"
+
+      - name: Lint
+        run: |
+          uv run ruff check src tests
+          uv run ruff format --check src tests
+
+      - name: Test
+        run: uv run pytest -q

see_your_agents-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+# Publishing a GitHub release (tag vX.Y.Z) builds the package and uploads it to PyPI through Trusted Publishing:
+# PyPI trusts this workflow in the `pypi` environment, so no token is stored anywhere.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.3  # no moving major tag is published for setup-uv
+
+      - name: The tag matches the package version
+        run: |
+          version=$(uv version --short)
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match the version in pyproject.toml ($version)"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/see-your-agents
+    permissions:
+      id-token: write  # Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

see_your_agents-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python: virtual environments, caches, built packages
+.venv/
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+
+# the static demo (uv run python demo/build.py)
+demo/dist/
+
+# rendered visual plans
+*.plan.html
+
+# local Claude Code state and worktrees; the project's skills are shared
+.claude/*
+!.claude/skills/
+
+# local research material, not part of the repository
+docs/competitors/
+
+.DS_Store

see_your_agents-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# Agent instructions
+
+The project's rules for coding agents are kept in one place, [CLAUDE.md](CLAUDE.md). They apply to every agent
+CLI, not only Claude Code: read that file before you change anything, and follow it as if it were this one.
+
+Then, depending on the task:
+
+- checks, commit style and pull requests: [CONTRIBUTING.md](CONTRIBUTING.md);
+- a new feature or module: [docs/adding-a-feature.md](docs/adding-a-feature.md) (the same recipe as the
+  `.claude/skills/add-feature/SKILL.md` skill);
+- the design and the security invariants: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+This file only points there, so the rules cannot drift apart: change CLAUDE.md, not this file.

see_your_agents-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/) (while it is 0.x, a minor version may change behaviour).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-04
+
+The first public release.
+
+### Added
+
+- **Board.** Every Claude Code and Codex CLI session on the machine, grouped by "Needs you", "Working",
+  "Your move", "Recently closed" and "Archive". Each card shows its title, project, branch, tickets, MR state, cost or
+  tokens, and how full the context window is. The same board is also available in the terminal (`sya ls`).
+- **Chat with any session.**
+  - Live Claude sessions are reached through a one-shot courier, through tmux, or through the optional VS Code
+    bridge.
+  - Stopped sessions are continued for one turn.
+  - Codex threads are reached through `codex queue`.
+  - Quote-reply, file attachments where the program supports them, and a ⌘K switcher.
+- **New sessions** from the page («+»), for Claude Code or Codex, with model, effort, permission or sandbox mode and
+  an optional worktree. Existing sessions can be forked.
+- **Supervisor.**
+  - A Claude Code session that watches the others over MCP.
+  - It writes digests and keeps the to-do list.
+  - It sends messages or starts agents only after you confirm.
+  - Optionally it reads Jira (read-only).
+- **Group chats** with the supervisor and any sessions, including Codex threads.
+- **To-do list** in a side dock, with urgent items, Jira links and a morning review.
+- **Permission approvals from the dashboard.**
+  - Claude Code's permission prompts, questions and plan approvals appear on the page through a local
+    `PermissionRequest` hook (`sya hooks install`). The terminal dialog stays open, and the first answer wins.
+  - Deciding needs a browser paired through a one-time link.
+- **Paired browser for every control action.** Any page request that changes something needs the pairing secret.
+- **Builder.** A Claude Code agent extends the dashboard itself on its own branch. It is sandboxed, and so are its
+  checks and preview. You get a preview, a diff, "Accept" and "Roll back"; a watchdog restarts the dashboard and rolls
+  back a version that does not come up.
+- **GitLab MR state** on cards through `glab` (read-only).
+- **Office view**, configurable agent looks, three page styles in light and dark, and a Mac kept awake while agents
+  work.
+- **UI in six languages:** English (the default), Russian, Spanish, German, French and Simplified Chinese.
+- **Providers.** Claude Code and Codex sit behind one provider interface, so another agent CLI is a folder plus a
+  registry line.
+
+[Unreleased]: https://github.com/vldplcd/see-your-agents/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/vldplcd/see-your-agents/releases/tag/v0.1.0

see_your_agents-0.1.0/CLAUDE.md

@@ -0,0 +1,27 @@
+# see-your-agents
+
+A local dashboard for Claude Code and Codex CLI sessions: a stdlib Python server (`uv run sya serve`, 127.0.0.1:8765),
+a DuckDB index of transcripts, a build-free page in plain JS. What is on screen: `docs/user-guide.md`; the docs index:
+`docs/README.md`. These rules are for every coding agent: `AGENTS.md` points here.
+
+- Structure: `docs/ARCHITECTURE.md`: layers (`core/` data, `app/` host, `features/<id>/` features, `web/` page
+  shell), the `Feature` manifest, the `SYA.feature` slots, security invariants.
+- A new feature or module: the `add-feature` skill (`.claude/skills/add-feature/SKILL.md`): a folder in `features/`
+  and one line in `features/__init__.py`; the host and other features are not edited.
+- Agent programs (Claude Code, Codex) are providers, `docs/providers.md`: a folder in
+  `core/providers/` and one line in the registry; features go through the session's provider, not to `claude` directly.
+- Checks. On a work branch, before each commit: ruff plus the tests of what you touched
+  (`uv run pytest -q tests/<area>`). The full suite (about 2.5 minutes) runs once before handing work back and
+  again before merging into `main`:
+  ```bash
+  uv run ruff check src tests && uv run ruff format --check src tests && uv run pytest -q
+  ```
+- Live check: your own server on a free port (`uv run sya serve --no-open --port 8771`), not 8765: that is the user's
+  dashboard. Write nothing to the user's `~/.claude`, `~/.codex` or `~/.config/see-your-agents`.
+- Style: short "why" docstrings, no noisy comments, ruff line-length 110. Docs, code comments and commit messages are
+  in English. Commits: one logical change each, subject `Area: what changed` (a feature id, `core`, `app`, `docs`,
+  `ci`), the body says why; pull requests and the security-sensitive areas: `CONTRIBUTING.md`.
+- UI text goes through `t()` (page and server), never a literal: keys in the owner's `i18n/en.json` and `i18n/ru.json`,
+  English by default; how-to in `docs/i18n.md`. Text an agent reads (prompts, tool descriptions, courier headers) is
+  English and never a catalog string.
+- The builder (an agent on its own branch) does not commit to `main` or merge into it: the user accepts the change.

see_your_agents-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of conduct
+
+Be decent. Talk to people the way you'd want to be talked to: stay on topic, assume good intent, disagree about
+code rather than about people. No harassment, insults, spam or trolling.
+
+The maintainers may edit or delete comments, close issues and pull requests, and block or ban anyone whose behaviour
+they find inappropriate, in this repository and in any space connected to it. They decide, and they don't have to
+justify it.
+
+To flag a problem, use GitHub's "Report content" on the comment or issue, or contact the maintainer on GitHub.