Metadata-Version: 2.4
Name: horus-harness
Version: 0.0.2
Summary: Project-centric continuity and control panel for official coding-agent CLIs
Author: Rafael M. J. Figueiredo
License: Apache-2.0
Project-URL: Homepage, https://github.com/rafaelmjf/horus-harness
Project-URL: Repository, https://github.com/rafaelmjf/horus-harness
Project-URL: Issues, https://github.com/rafaelmjf/horus-harness/issues
Keywords: claude-code,codex,coding-agents,continuity,cli,dashboard
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# Horus

> Project-centric continuity and control panel for official coding-agent CLIs.

Horus keeps a project understandable over time - across agents (Claude Code,
Codex), accounts, environments, and days. It does not reimplement an agent loop
and does not use model API keys; it wraps the official CLIs and keeps durable
project state in repo-local `.horus/` files that native tools can read even when
Horus is not running.

**Status:** early (alpha). MVP0/MVP1 shipped: continuity scaffolding, health
checks, a read-only dashboard, session/closure commands, instruction-block sync,
and agent-delegated continuity routines. Agent execution is still intentionally
small and incremental.

## Install

With [uv](https://docs.astral.sh/uv/):

```sh
uv tool install horus-harness     # installs the `horus` command
# or run without installing:
uvx --from horus-harness horus --help
```

With pip:

```sh
pip install horus-harness
```

## Commands

```sh
horus init [path]                 # scaffold .horus/ + managed AGENTS.md/CLAUDE.md blocks
horus doctor [project|instructions|all]   # continuity + instruction-drift health checks
horus dashboard                   # local, read-only multi-project web view (127.0.0.1:8765)
horus app                         # borderless animated companion; click opens dashboard
horus session new "<title>"       # create a dated session summary from the template
horus close                       # verify continuity, Codex usage, and print the closure ritual
horus close --usage-threshold 90  # warn when Codex context or rate-limit usage reaches a percent
horus usage check                 # check the same native-app usage signal directly
horus hook install --target codex # install a Codex Stop hook for automatic usage nudges
horus consolidate                 # route/prune/distill .horus lanes; prints the agent ritual
horus distill-history             # compress a large log into curated history.md
horus infer                       # bootstrap/refresh .horus from canonical docs; prints the ritual
horus skill install --target all  # install/update bundled Claude Code + Codex skills
horus reconcile instructions      # deterministic AGENTS.md <-> CLAUDE.md managed-block sync
horus forget <path> | horus prune # manage the dashboard's project registry
```

## Repo-local continuity

```text
.horus/
  project.md      # vision, shape, boundaries, current focus
  roadmap.md      # open action points
  features.md     # shipped / in-progress / planned capability ledger
  decisions.md    # durable decisions + reasoning
  history.md      # curated lessons / "bumps in the road"
  sessions/       # local session summaries (gitignored by default)
```

`AGENTS.md` and `CLAUDE.md` stay native; Horus only syncs the marked
`<!-- HORUS:BEGIN shared-instructions -->` block and detects drift elsewhere.
Horus project skills are scaffolded for both Claude Code (`.claude/skills`) and
Codex (`.agents/skills`).

`horus close` also performs a best-effort read of local Codex rollout telemetry
from `$CODEX_HOME/sessions` when available. If the latest project turn is near
the configured usage threshold, Horus nudges you to run the closure ritual before
starting another large turn.

For a native Codex warning, run `horus hook install --target codex --path .`.
That writes a project-local `.codex/hooks.json` `Stop` hook which calls
`horus usage check --hook` after turns. Codex may ask you to review/trust the hook
with `/hooks` before it runs.

## License

Apache-2.0
