cc-hub 0.2.1__tar.gz

cc_hub-0.2.1/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

cc_hub-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+      - run: uv build
+      - name: smoke test the wheel
+        shell: bash
+        run: |
+          uvx --from dist/*.whl cc-hub version
+          uvx --from dist/*.whl cc-hub init "${RUNNER_TEMP}/hub" --no-git
+          uvx --from dist/*.whl cc-hub --hub "${RUNNER_TEMP}/hub" doctor --json

cc_hub-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  publish-pypi:
+    # Opt-in: set the repository variable PUBLISH_PYPI to "true" once a PyPI
+    # trusted publisher exists. Independent of the GitHub release, so a PyPI
+    # outage must not block the release assets.
+    if: vars.PUBLISH_PYPI == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

cc_hub-0.2.1/.gitignore

@@ -0,0 +1,9 @@
+.superpowers/
+.venv/
+dist/
+build/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

cc_hub-0.2.1/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+## 0.2.1 - 2026-09-30
+
+Template fixes; no command changes. The cron guidance is now checked against
+the cc-connect 1.5.0 source. First release published on PyPI:
+`uv tool install cc-hub`.
+
+### Fixed
+
+- Cron tasks now get the session mode they declare. `BOOTSTRAP.md`,
+  `cron/README.md` and `hub-cc-connect` register a task with
+  `--session-mode <session> --desc "hub:<name>"`, where `<name>` is the file
+  name without `.md`. Bootstrap checks `cc-connect cron list` first and skips
+  tasks that are already registered. Before this, the `session` field was
+  never passed on, so `memory-consolidate` ran inside the reused chat session.
+- `hub-cc-connect` lists and edits schedules with `cc-connect cron list`,
+  `cron edit` and `cron del`. It only deletes a schedule when the user asks.
+  It also says a task belongs to the chat it was registered from.
+- `hub-projects` no longer points at "hub-adapt goal 4", which 0.2.0 removed.
+  After `projects add` under Codex, the agent tells the user to add the path
+  to `writable_roots` (`docs/codex-sandbox.md`) and leaves the sandbox alone.
+- `AGENTS.md` refers to `hub-cc-connect` for scheduling instead of repeating
+  an incomplete command.
+
+### Migration notes
+
+- Run `cc-hub update` to get the fixed `AGENTS.md`, `BOOTSTRAP.md`,
+  `cron/README.md` and skills.
+- A hub bootstrapped with 0.1.0 or 0.2.0 registered `memory-consolidate`
+  without a session mode or description. Ask the agent to fix it, or do it
+  yourself: find the task's id with `cc-connect cron list` (it shows the start
+  of the prompt), then run
+  `cc-connect cron edit <id> session_mode new_per_run` and
+  `cc-connect cron edit <id> description hub:memory-consolidate`.
+
+## 0.2.0 - 2026-09-29
+
+The hub is a convention and a router. Permissions and background work belong
+to cc-connect and the agent runtime, so the hub no longer duplicates them.
+
+### Removed
+
+- `cc-hub hook` (pre-tool-use blocklist, post-tool-use audit log, `snippet`,
+  `test`) and the `[hooks]` table in `hub.toml`. Approvals stay with
+  cc-connect's `mode`, and permissions with the agent runtime's own settings.
+  A live test on native Windows also showed the hook failing open under both
+  Claude Code and Codex.
+- `cc-hub jobs` and the `hub-jobs` skill. Long-running work uses the agent
+  runtime's own background facilities, which cc-connect ends together with
+  the chat session (`/new`, `/switch`, idle timeout, daemon restart).
+- `doctor` checks `jobs-lost` and the hook part of `pointers`.
+- `cc-hub hosts check|run|push|pull`. `hosts.toml` and `hosts list` remain the
+  registry; the agent connects with `ssh` and `scp` itself (`hub-hosts`).
+- `cc-hub memory stats`; `doctor` already reports the memory budgets.
+- `doctor` check `daemon-path` and the daemon-visibility note in `ENV.md`: the
+  PATH cc-connect gives the agent is cc-connect's configuration.
+- The permissions goal of `hub-adapt` (deny reads, Codex `writable_roots`).
+  Permissions and sandbox settings are left to the user and the runtime; see
+  `docs/codex-sandbox.md` for making projects writable under Codex.
+
+### Added
+
+- `doctor` check `stale-hooks`: warns when a hook configuration in the hub
+  still calls `cc-hub hook`.
+- `update` backs up and removes framework files that are no longer shipped
+  (`skills/hub-jobs/SKILL.md`).
+- `projects list --json` and `projects show --json` include `resolved`, the
+  absolute path; stored paths stay portable (`~/...`).
+
+### Fixed
+
+- `doctor` `pointers` judges only runtimes set up in this hub, so an installed
+  but unused agent is no longer a warning. `CLAUDE.md` is optional, as
+  `hub-adapt` says; one without `@AGENTS.md` is reported because it hides
+  `AGENTS.md`.
+- `where` prints the package location even when no hub is found (exit 1).
+- `memory search` ignores HTML comments, such as template notes.
+- `update` edits `hub.toml` in place and keeps your comments and layout.
+- `projects list` and `projects show` print absolute paths instead of `~/...`.
+- Install docs no longer point at PyPI, where cc-hub is not published yet, and
+  warn against installing from a shell inside the Claude desktop app on
+  Windows. The release workflow publishes to PyPI only when the repository
+  variable `PUBLISH_PYPI` is `true`.
+
+### Migration notes
+
+- Run `cc-hub update`. It removes `skills/hub-jobs/SKILL.md`; the backup is in
+  `.cc-hub/backups/<old version>/`.
+- Remove the `cc-hub hook ...` entries from `.claude/settings.json` and
+  `.codex/hooks.json`, or ask the agent to run the `hub-adapt` skill;
+  `cc-hub doctor` lists leftovers as `stale-hooks`. Until then every tool call
+  runs a command that no longer exists, and on Linux and macOS Claude Code
+  treats its exit status as a block.
+- The `jobs/` and `logs/` directories and the `[hooks]` table in `hub.toml`
+  are no longer used and can be deleted.
+
+## 0.1.0 - 2026-09-23
+
+### Added
+
+- `cc-hub init`, `doctor`, `update`: seed, check and upgrade a hub directory.
+- `cc-hub env`: machine probe written to `ENV.md` / `env.json`.
+- `cc-hub memory`: daily logs, search, recent, stats.
+- `cc-hub projects`: registry of local project directories.
+- `cc-hub jobs`: detached background jobs with a supervising runner.
+- `cc-hub hosts`: ssh/scp with base64-wrapped remote commands.
+- `cc-hub hook`: pre-tool-use blocklist, post-tool-use audit log, snippet.
+- Blocklist rule `find-delete` for recursive deletes of root or home via `find`.
+- `cc-hub link`: symlink / junction / copy.
+- Hub templates: `AGENTS.md`, `BOOTSTRAP.md`, persona files, six `hub-*` skills,
+  `cron/memory-consolidate.md`.
+
+### Known limitations
+
+- The Codex hook payload shape is inferred from the documentation, not verified
+  against a real Codex run; the fixtures in `tests/fixtures` encode that guess.
+- The native-Windows code paths (junctions, `taskkill`, `.cmd` shims) are
+  reasoned about rather than CI-executed: CI runs the suite on windows-latest,
+  but the jobs and kill paths are not exercised there.
+
+### Migration notes
+
+First release; nothing to migrate.

cc_hub-0.2.1/LICENSE

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

cc_hub-0.2.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: cc-hub
+Version: 0.2.1
+Summary: A hub directory convention and CLI for coding agents launched by cc-connect
+Project-URL: Homepage, https://github.com/Jenwein/cc-hub
+Author: Jenwein
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cc-connect,claude-code,codex,workspace
+Requires-Python: >=3.11
+Requires-Dist: charset-normalizer>=3
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# cc-hub
+
+A hub directory convention and CLI for coding agents launched by
+[cc-connect](https://github.com/chenhg5/cc-connect).
+
+cc-connect bridges Claude Code, Codex and other agents to chat platforms and
+starts the agent in a `work_dir`. cc-hub turns that directory into a **hub**:
+the agent's home base on your machine, with a persona, memory, and a registry
+of your projects and remote hosts. Permissions and background work stay with
+cc-connect and the agent runtime; the hub adds conventions and routing, not
+another layer of either.
+
+The hub is agent-agnostic. It ships no Claude- or Codex-specific files; on
+first run the agent creates the pointers its own ecosystem needs (`hub-adapt`).
+
+## Quick start
+
+    uv tool install cc-hub
+    cc-hub init                     # creates ~/.cc-hub
+    cc-hub doctor
+
+Install from a regular terminal; on Windows not from a shell inside the
+Claude desktop app (see [docs/install.md](docs/install.md)).
+
+Point cc-connect at the hub (`work_dir = "/home/you/.cc-hub"`, see
+[docs/cc-connect.md](docs/cc-connect.md)) and send the first message. The agent
+follows `BOOTSTRAP.md`: names itself, learns who you are, registers projects,
+adapts to its runtime, and deletes the bootstrap file.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `cc-hub init [dir]` | Seed a hub. Existing files are never overwritten. |
+| `cc-hub doctor [--fix] [--json]` | Health checks: budgets, pointers, leftover hooks. |
+| `cc-hub update [--dry-run]` | Refresh framework-owned files; user files untouched; backups kept. |
+| `cc-hub env` | Probe the machine and write `ENV.md` / `env.json`. |
+| `cc-hub memory log\|search\|recent` | Daily logs and long-term memory. |
+| `cc-hub projects list\|show\|add\|remove` | Registry of local project directories. |
+| `cc-hub hosts list` | Registry of remote machines; the agent connects with ssh itself. |
+| `cc-hub link <src> <dst>` | Symlink, junction or copy (platform decides). |
+
+## Hub layout
+
+    ~/.cc-hub/
+    ├── AGENTS.md  AGENTS.local.md  BOOTSTRAP.md      instructions
+    ├── SOUL.md  IDENTITY.md  USER.md                 persona and user
+    ├── MEMORY.md  memory/YYYY-MM-DD.md               memory
+    ├── projects.toml  hosts.toml  hub.toml           registries and config
+    ├── skills/  cron/  scripts/  secrets/            skills, scheduled prompts, your scripts, credentials
+    └── ENV.md  env.json                              generated state (gitignored)
+
+Framework-owned files (`AGENTS.md`, `BOOTSTRAP.md`, `skills/hub-*`, `cron/README.md`)
+are replaced by `cc-hub update`. Everything else is yours.
+
+## Documentation
+
+- [Install and upgrade](docs/install.md)
+- [cc-connect configuration](docs/cc-connect.md)
+- [Windows notes](docs/windows.md)
+- [Codex sandbox notes](docs/codex-sandbox.md)
+- [Manual acceptance checklist](docs/acceptance.md)
+- [Design spec](docs/superpowers/specs/2026-09-22-cc-hub-design.md)
+
+中文说明见 [README.zh-CN.md](README.zh-CN.md)。
+
+## License
+
+MIT

cc_hub-0.2.1/README.md

@@ -0,0 +1,69 @@
+# cc-hub
+
+A hub directory convention and CLI for coding agents launched by
+[cc-connect](https://github.com/chenhg5/cc-connect).
+
+cc-connect bridges Claude Code, Codex and other agents to chat platforms and
+starts the agent in a `work_dir`. cc-hub turns that directory into a **hub**:
+the agent's home base on your machine, with a persona, memory, and a registry
+of your projects and remote hosts. Permissions and background work stay with
+cc-connect and the agent runtime; the hub adds conventions and routing, not
+another layer of either.
+
+The hub is agent-agnostic. It ships no Claude- or Codex-specific files; on
+first run the agent creates the pointers its own ecosystem needs (`hub-adapt`).
+
+## Quick start
+
+    uv tool install cc-hub
+    cc-hub init                     # creates ~/.cc-hub
+    cc-hub doctor
+
+Install from a regular terminal; on Windows not from a shell inside the
+Claude desktop app (see [docs/install.md](docs/install.md)).
+
+Point cc-connect at the hub (`work_dir = "/home/you/.cc-hub"`, see
+[docs/cc-connect.md](docs/cc-connect.md)) and send the first message. The agent
+follows `BOOTSTRAP.md`: names itself, learns who you are, registers projects,
+adapts to its runtime, and deletes the bootstrap file.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `cc-hub init [dir]` | Seed a hub. Existing files are never overwritten. |
+| `cc-hub doctor [--fix] [--json]` | Health checks: budgets, pointers, leftover hooks. |
+| `cc-hub update [--dry-run]` | Refresh framework-owned files; user files untouched; backups kept. |
+| `cc-hub env` | Probe the machine and write `ENV.md` / `env.json`. |
+| `cc-hub memory log\|search\|recent` | Daily logs and long-term memory. |
+| `cc-hub projects list\|show\|add\|remove` | Registry of local project directories. |
+| `cc-hub hosts list` | Registry of remote machines; the agent connects with ssh itself. |
+| `cc-hub link <src> <dst>` | Symlink, junction or copy (platform decides). |
+
+## Hub layout
+
+    ~/.cc-hub/
+    ├── AGENTS.md  AGENTS.local.md  BOOTSTRAP.md      instructions
+    ├── SOUL.md  IDENTITY.md  USER.md                 persona and user
+    ├── MEMORY.md  memory/YYYY-MM-DD.md               memory
+    ├── projects.toml  hosts.toml  hub.toml           registries and config
+    ├── skills/  cron/  scripts/  secrets/            skills, scheduled prompts, your scripts, credentials
+    └── ENV.md  env.json                              generated state (gitignored)
+
+Framework-owned files (`AGENTS.md`, `BOOTSTRAP.md`, `skills/hub-*`, `cron/README.md`)
+are replaced by `cc-hub update`. Everything else is yours.
+
+## Documentation
+
+- [Install and upgrade](docs/install.md)
+- [cc-connect configuration](docs/cc-connect.md)
+- [Windows notes](docs/windows.md)
+- [Codex sandbox notes](docs/codex-sandbox.md)
+- [Manual acceptance checklist](docs/acceptance.md)
+- [Design spec](docs/superpowers/specs/2026-09-22-cc-hub-design.md)
+
+中文说明见 [README.zh-CN.md](README.zh-CN.md)。
+
+## License
+
+MIT

cc_hub-0.2.1/README.zh-CN.md

@@ -0,0 +1,36 @@
+# cc-hub
+
+给 [cc-connect](https://github.com/chenhg5/cc-connect) 拉起的编码 agent 用的"总站"：一套目录约定加一个命令行工具。
+
+cc-connect 把 Claude Code、Codex 等 agent 接到飞书、微信、Telegram 等 IM，并在 `work_dir` 里启动 agent。cc-hub 把这个目录变成 agent 在你机器上的家：人格、记忆、项目和远程主机注册表。权限和后台任务交给 cc-connect 与 agent 运行时自己处理，总站只提供规范和路由。
+
+总站与 agent 无关：不带任何 Claude 或 Codex 专属文件，agent 首次运行时按自己的生态生成指针（`hub-adapt`）。
+
+## 快速开始
+
+    uv tool install cc-hub
+    cc-hub init          # 创建 ~/.cc-hub
+    cc-hub doctor
+
+请在普通终端里安装；Windows 上不要在 Claude 桌面版内的 shell 里装（原因见 [docs/install.md](docs/install.md)）。
+
+把 cc-connect 的 `work_dir` 指向总站（见 [docs/cc-connect.md](docs/cc-connect.md)），发第一条消息。agent 会按 `BOOTSTRAP.md` 起名、认识你、登记项目、适配自己的运行时，然后删除引导文件。
+
+## 命令
+
+| 命令 | 用途 |
+|---|---|
+| `cc-hub init [dir]` | 播种总站，已有文件不覆盖 |
+| `cc-hub doctor [--fix] [--json]` | 体检：预算、指针、残留钩子 |
+| `cc-hub update [--dry-run]` | 只更新框架拥有的文件，用户文件不动，旧版本有备份 |
+| `cc-hub env` | 探测机器，写 `ENV.md` 和 `env.json` |
+| `cc-hub memory log\|search\|recent` | 日志与长期记忆 |
+| `cc-hub projects list\|show\|add\|remove` | 本机项目注册表 |
+| `cc-hub hosts list` | 远程主机注册表，agent 自己用 ssh 连接 |
+| `cc-hub link <src> <dst>` | symlink / junction / 复制，按平台自动选 |
+
+其余文档见英文 README 的链接。
+
+## 许可证
+
+MIT

cc_hub-0.2.1/docs/acceptance.md

@@ -0,0 +1,23 @@
+# Manual acceptance checklist
+
+Environment: WSL2, cc-connect running as a daemon, Claude Code as the agent,
+one chat platform (Feishu or any other).
+
+1. Install cc-hub from a regular terminal (see `install.md`), `cc-hub init`,
+   `cc-hub doctor`: everything green
+   except `bootstrap-pending` and `env-stale`.
+2. Configure cc-connect `work_dir` and `env.PATH`, restart the daemon.
+3. Send the first message. The agent runs bootstrap: asks for a name, writes
+   `IDENTITY.md` and `USER.md`, runs `hub-adapt`, registers the cron task,
+   deletes `BOOTSTRAP.md`.
+4. `cc-hub doctor`: all green.
+5. Ask the agent to remember something. `memory/` has today's file;
+   `cc-hub memory search` finds it.
+6. Ask the agent to run the tests of a registered project by name. It finds
+   the path in `projects.toml`, runs them there, and logs the outcome.
+7. Ask the agent to run a command on a registered remote host by name. It
+   finds the target, port and key in `hosts.toml` and connects with ssh.
+8. Ask the agent to send a file back to the chat. It arrives.
+9. Bump the package version and run `cc-hub update`: `AGENTS.md` changes,
+   `SOUL.md`, `USER.md` and `memory/` do not, and `.cc-hub/backups/` holds
+   the previous version.

cc_hub-0.2.1/docs/cc-connect.md

@@ -0,0 +1,64 @@
+# cc-connect configuration
+
+Minimal `[[projects]]` entry pointing a Claude Code bot at the hub:
+
+    [[projects]]
+    name = "hub"
+    admin_from = "<your user id on the platform>"
+
+    [projects.agent]
+    type = "claudecode"
+
+    [projects.agent.options]
+    work_dir = "/home/you/.cc-hub"     # absolute path; ~ expansion needs cc-connect > 1.5.1
+    mode = "default"                    # approvals are relayed to the chat
+
+    [projects.agent.options.env]
+    PATH = "/home/you/.local/bin:/usr/local/bin:/usr/bin:/bin"
+    PYTHONUTF8 = "1"
+    CC_HUB_DIR = "/home/you/.cc-hub"  # only needed when the hub is not ~/.cc-hub
+
+    [[projects.platforms]]
+    type = "feishu"
+
+    [projects.platforms.options]
+    app_id = "${FEISHU_APP_ID}"
+    app_secret = "${FEISHU_APP_SECRET}"
+    allow_from = "*"
+
+For Codex use `type = "codex"` with the same `work_dir` and `env`, and read
+[codex-sandbox.md](codex-sandbox.md).
+
+## PATH under a daemon
+
+`cc-connect daemon install` runs cc-connect from systemd, launchd or the
+Windows Task Scheduler. Those do not read your shell profile, so PATH is often
+just the system directories and `cc-hub`, `uv`, `claude` or `codex` are not
+found. Put the full PATH in `[projects.agent.options.env]` as above.
+`ENV.md` lists absolute paths the agent can fall back to.
+
+## What the agent uses
+
+- Attachments you send land in `<hub>/.cc-connect/attachments/<message id>/`;
+  cc-connect appends their absolute paths to the prompt.
+- The agent sends files back with `cc-connect send --file <absolute path>`
+  (`--image`, `--tts`). 50 MB limit.
+- Scheduled prompts: `cc-connect cron add --cron "<expr>" --prompt "<text>"
+  --session-mode <reuse|new_per_run> --desc "hub:<name>"`. The hub keeps
+  definitions in `cron/*.md`; bootstrap registers the defaults in the chat it
+  runs in, and skips any whose `hub:<name>` is already in `cc-connect cron list`.
+- `/dir <path>` in the chat switches the working directory for the *next*
+  session only. Keep `work_dir` on the hub and let the agent `cd` into projects.
+
+## Approvals
+
+`mode = "default"` relays every tool approval to the chat. With `/mode yolo`
+or "allow all" the decision rests with the agent runtime's own permission
+settings; the hub adds no enforcement of its own.
+
+## Sessions and background work
+
+cc-connect keeps one agent process per chat session and ends it, together
+with everything it started, on `/new`, `/switch`, a turn that stays silent
+longer than `idle_timeout_mins`, or a daemon restart. Background tasks and
+subagents the agent starts therefore live as long as that session.

cc_hub-0.2.1/docs/codex-sandbox.md

@@ -0,0 +1,33 @@
+# Codex sandbox notes
+
+cc-connect starts Codex with `codex exec --cd <hub> --sandbox workspace-write`
+by default. Inside that sandbox only the working directory (the hub) and
+`writable_roots` are writable, and the restriction is inherited by every
+child process the agent starts.
+
+## Make registered projects writable
+
+Add their paths to `writable_roots` in `.codex/config.toml` inside the hub
+(the hub is the Codex project directory, so this file applies once the hub
+is trusted):
+
+    [sandbox_workspace_write]
+    writable_roots = ["/home/you/dev/project-a", "/home/you/dev/project-b"]
+
+cc-hub does not change Codex's sandbox settings: add the paths yourself, and
+again after each `cc-hub projects add`. If Codex rejects the key at project
+level, put the same table in `~/.codex/config.toml` instead.
+
+Alternative: pass `--add-dir <path>` through cc-connect's agent options for
+each project.
+
+## One-time trust
+
+Run `codex` interactively once in the hub and mark the directory trusted.
+Without trust Codex ignores `.codex/config.toml`, so `writable_roots` would
+not apply.
+
+## Full access
+
+`--dangerously-bypass-approvals-and-sandbox` (cc-connect `mode = "yolo"`)
+removes the sandbox entirely; `writable_roots` no longer matters.

cc_hub-0.2.1/docs/install.md

@@ -0,0 +1,70 @@
+# Install and upgrade
+
+## Requirements
+
+- [uv](https://docs.astral.sh/uv/) (single binary; installs Python 3.11+ itself if needed)
+- OpenSSH client if you use `cc-hub hosts`
+- git (optional; `cc-hub init` initializes a repository in the hub)
+
+## Install
+
+From PyPI (0.2.1 and later):
+
+    uv tool install cc-hub
+    cc-hub version
+
+Or a released tag straight from GitHub:
+
+    uv tool install git+https://github.com/Jenwein/cc-hub.git@v0.2.1
+
+Or download the wheel attached to the GitHub release and install that file:
+
+    uv tool install ./cc_hub-0.2.1-py3-none-any.whl
+
+`uv tool install` puts `cc-hub` in `~/.local/bin` (Windows: `%USERPROFILE%\.local\bin`).
+Make sure that directory is on your PATH; `uv tool update-shell` can add it.
+
+**Install from a regular terminal** (Windows Terminal, PowerShell, a Linux or
+macOS shell). On Windows, a shell running inside the Claude desktop app is part
+of a packaged (MSIX) app: new folders it creates under `%APPDATA%` go to the
+app's private storage, so a cc-hub installed there is invisible to cc-connect
+and to the agents it starts. The symptom is `uv trampoline failed to
+canonicalize script path`; reinstall from a regular terminal.
+
+## Create the hub
+
+    cc-hub init              # ~/.cc-hub
+    cc-hub init ~/my-hub     # anywhere else
+
+The hub must not live inside another git repository, and it must not be the
+root of one either; `init` refuses both. If the hub is not `~/.cc-hub`, set
+`CC_HUB_DIR` to its absolute path in cc-connect's
+`[projects.agent.options.env]` so every `cc-hub` call finds it from any
+working directory.
+Treat the hub as private data: commit it to a private repository if you want
+backups. `secrets/`, generated files and agent pointers are already gitignored.
+
+## Connect cc-connect
+
+See [cc-connect.md](cc-connect.md). Then send the agent its first message.
+
+## Check
+
+    cc-hub doctor
+
+Warnings about `bootstrap-pending` and `env-stale` disappear after the first
+conversation. When cc-connect runs as a service, make sure it can find
+`cc-hub` and `uv`; see the PATH notes in [cc-connect.md](cc-connect.md).
+
+## Upgrade
+
+    uv tool upgrade cc-hub    # installed from PyPI
+    uv tool install --force git+https://github.com/Jenwein/cc-hub.git@<new tag>   # from GitHub
+    cc-hub update --dry-run   # see what would change
+    cc-hub update
+
+`update` replaces only framework-owned files (`AGENTS.md`, `BOOTSTRAP.md`,
+`skills/hub-*`, `cron/README.md`, `cron/memory-consolidate.md`, `.gitignore`)
+and merges new keys into `hub.toml`. Previous versions are copied to
+`.cc-hub/backups/<old version>/`. Read the migration notes in `CHANGELOG.md`
+before upgrading across minor versions.