observeco 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. observeco-0.1.0/.codegraph/.gitignore +16 -0
  2. observeco-0.1.0/.codegraph/codegraph.db +0 -0
  3. observeco-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md +30 -0
  4. observeco-0.1.0/.github/workflows/ci.yml +46 -0
  5. observeco-0.1.0/.github/workflows/publish.yml +35 -0
  6. observeco-0.1.0/.gitignore +31 -0
  7. observeco-0.1.0/CONTRIBUTING.md +38 -0
  8. observeco-0.1.0/LICENSE +21 -0
  9. observeco-0.1.0/PKG-INFO +188 -0
  10. observeco-0.1.0/README.md +147 -0
  11. observeco-0.1.0/assets/banner.svg +88 -0
  12. observeco-0.1.0/assets/dashboard-fleet.png +0 -0
  13. observeco-0.1.0/assets/dashboard-preview.png +0 -0
  14. observeco-0.1.0/assets/logo.svg +31 -0
  15. observeco-0.1.0/assets/terminal-demo.gif +0 -0
  16. observeco-0.1.0/assets/terminal-demo.svg +51 -0
  17. observeco-0.1.0/brand/LOGO_STYLE_GUIDE.md +62 -0
  18. observeco-0.1.0/brand/observeco-horizontal.jpg +0 -0
  19. observeco-0.1.0/brand/observeco-monochrome.jpg +0 -0
  20. observeco-0.1.0/brand/observeco-primary.jpg +0 -0
  21. observeco-0.1.0/brand/observeco-white.jpg +0 -0
  22. observeco-0.1.0/docs/commands.md +86 -0
  23. observeco-0.1.0/docs/comparison.md +99 -0
  24. observeco-0.1.0/docs/dashboard.md +33 -0
  25. observeco-0.1.0/docs/installation.md +38 -0
  26. observeco-0.1.0/docs/launch-drafts.md +229 -0
  27. observeco-0.1.0/docs/pro.md +21 -0
  28. observeco-0.1.0/docs/quickstart.md +35 -0
  29. observeco-0.1.0/pyproject.toml +70 -0
  30. observeco-0.1.0/specs/codegraph-evaluation.md +99 -0
  31. observeco-0.1.0/specs/comprehensive-launch-plan.md +225 -0
  32. observeco-0.1.0/specs/execution-plan.md +681 -0
  33. observeco-0.1.0/specs/expectations-gap.md +59 -0
  34. observeco-0.1.0/specs/market-feedback.md +64 -0
  35. observeco-0.1.0/specs/marketing-plan.md +428 -0
  36. observeco-0.1.0/specs/unified-dashboard.md +849 -0
  37. observeco-0.1.0/src/observeco/__init__.py +3 -0
  38. observeco-0.1.0/src/observeco/__main__.py +4 -0
  39. observeco-0.1.0/src/observeco/auto_detect.py +91 -0
  40. observeco-0.1.0/src/observeco/billing.py +217 -0
  41. observeco-0.1.0/src/observeco/chisel/__init__.py +1 -0
  42. observeco-0.1.0/src/observeco/chisel/drift.py +87 -0
  43. observeco-0.1.0/src/observeco/chisel/trim.py +122 -0
  44. observeco-0.1.0/src/observeco/clawforge/__init__.py +1 -0
  45. observeco-0.1.0/src/observeco/clawforge/garden.py +210 -0
  46. observeco-0.1.0/src/observeco/clawforge/load.py +110 -0
  47. observeco-0.1.0/src/observeco/clawforge/profile.py +151 -0
  48. observeco-0.1.0/src/observeco/cli/billing_wire.py +79 -0
  49. observeco-0.1.0/src/observeco/cli.py +193 -0
  50. observeco-0.1.0/src/observeco/config.py +173 -0
  51. observeco-0.1.0/src/observeco/dashboard/__init__.py +1 -0
  52. observeco-0.1.0/src/observeco/dashboard/otel.py +109 -0
  53. observeco-0.1.0/src/observeco/dashboard/server.py +1107 -0
  54. observeco-0.1.0/src/observeco/dashboard/static/htmx.min.js +1 -0
  55. observeco-0.1.0/src/observeco/dashboard/templates/index.html +435 -0
  56. observeco-0.1.0/src/observeco/db.py +443 -0
  57. observeco-0.1.0/src/observeco/graph/__init__.py +1 -0
  58. observeco-0.1.0/src/observeco/graph/cli.py +147 -0
  59. observeco-0.1.0/src/observeco/graph/db.py +367 -0
  60. observeco-0.1.0/src/observeco/graph/extractor.py +295 -0
  61. observeco-0.1.0/src/observeco/graph/indexer.py +125 -0
  62. observeco-0.1.0/src/observeco/graph/watch.py +118 -0
  63. observeco-0.1.0/src/observeco/heal.py +353 -0
  64. observeco-0.1.0/src/observeco/mcp_server.py +336 -0
  65. observeco-0.1.0/src/observeco/pulse/__init__.py +1 -0
  66. observeco-0.1.0/src/observeco/pulse/check.py +144 -0
  67. observeco-0.1.0/src/observeco/pulse/circuit.py +71 -0
  68. observeco-0.1.0/src/observeco/snapshot.py +226 -0
  69. observeco-0.1.0/src/observeco/watch.py +109 -0
  70. observeco-0.1.0/tests/test_billing.py +51 -0
  71. observeco-0.1.0/tests/test_chisel.py +61 -0
  72. observeco-0.1.0/tests/test_clawforge.py +92 -0
  73. observeco-0.1.0/tests/test_cli.py +87 -0
  74. observeco-0.1.0/tests/test_infra.py +39 -0
  75. observeco-0.1.0/tests/test_pulse.py +43 -0
@@ -0,0 +1,16 @@
1
+ # CodeGraph data files
2
+ # These are local to each machine and should not be committed
3
+
4
+ # Database
5
+ *.db
6
+ *.db-wal
7
+ *.db-shm
8
+
9
+ # Cache
10
+ cache/
11
+
12
+ # Logs
13
+ *.log
14
+
15
+ # Hook markers
16
+ .dirty
Binary file
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: Bug Report
3
+ about: Report a bug to help improve ObserveCo
4
+ title: "[Bug] "
5
+ labels: bug
6
+ assignees: ""
7
+ ---
8
+
9
+ **Describe the bug**
10
+ A clear and concise description of what the bug is.
11
+
12
+ **To Reproduce**
13
+ Steps to reproduce the behavior:
14
+ 1. Run `...`
15
+ 2. See error
16
+
17
+ **Expected behavior**
18
+ What you expected to happen instead.
19
+
20
+ **Screenshots / Terminal Output**
21
+ If applicable, paste terminal output or screenshots.
22
+
23
+ **Environment (please complete):**
24
+ - OS: [e.g. macOS 15, Ubuntu 22.04, Windows 11]
25
+ - Python version: [e.g. 3.11, 3.12]
26
+ - Install method: [e.g. `pip install`, cloned repo, etc.]
27
+ - `observeco --version` output:
28
+
29
+ **Additional context**
30
+ Add any other context about the problem here.
@@ -0,0 +1,46 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ test:
11
+ name: "Python ${{ matrix.python-version }} on ${{ matrix.os }}"
12
+ runs-on: ${{ matrix.os }}
13
+ strategy:
14
+ fail-fast: false
15
+ matrix:
16
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
17
+ os: [ubuntu-latest, macos-latest]
18
+
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+
22
+ - name: Set up Python ${{ matrix.python-version }}
23
+ uses: actions/setup-python@v5
24
+ with:
25
+ python-version: ${{ matrix.python-version }}
26
+ cache: "pip"
27
+ cache-dependency-path: pyproject.toml
28
+
29
+ - name: Install dependencies
30
+ run: |
31
+ python -m pip install --upgrade pip
32
+ pip install -e ".[dev,dashboard]"
33
+
34
+ - name: Lint with ruff
35
+ run: ruff check src/observeco/
36
+
37
+ - name: Type check with mypy
38
+ run: mypy src/observeco/
39
+
40
+ - name: Run tests
41
+ run: pytest tests/ -v --tb=short --cov=observeco --cov-report=term-missing
42
+
43
+ - name: Build package
44
+ run: |
45
+ pip install build
46
+ python -m build --wheel --sdist .
@@ -0,0 +1,35 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ jobs:
9
+ publish:
10
+ name: Build and publish to PyPI
11
+ runs-on: ubuntu-latest
12
+ permissions:
13
+ contents: read
14
+ id-token: write # needed for trusted publishing
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Set up Python 3.12
20
+ uses: actions/setup-python@v5
21
+ with:
22
+ python-version: "3.12"
23
+ cache: "pip"
24
+ cache-dependency-path: pyproject.toml
25
+
26
+ - name: Install build tools
27
+ run: |
28
+ python -m pip install --upgrade pip
29
+ pip install build
30
+
31
+ - name: Build wheel and sdist
32
+ run: python -m build --wheel --sdist .
33
+
34
+ - name: Publish to PyPI
35
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,31 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv/
6
+ venv/
7
+ env/
8
+
9
+ # IDE
10
+ .vscode/
11
+ .idea/
12
+ *.swp
13
+ *.swo
14
+
15
+ # OS
16
+ .DS_Store
17
+ Thumbs.db
18
+
19
+ # Build
20
+ dist/
21
+ build/
22
+ *.egg
23
+
24
+ # Environment
25
+ .env
26
+ *.env.local
27
+
28
+ # Docs build
29
+ website/node_modules/
30
+ website/.docusaurus/
31
+ website/build/
@@ -0,0 +1,38 @@
1
+ # Contributing
2
+
3
+ ## Development Setup
4
+
5
+ ```bash
6
+ git clone https://github.com/observeco/observeco
7
+ cd observeco
8
+ python3 -m venv .venv
9
+ source .venv/bin/activate
10
+ pip install -e ".[dev]"
11
+ ```
12
+
13
+ ## Code Style
14
+
15
+ - Ruff for linting and formatting
16
+ - Mypy for type checking (strict mode)
17
+ - Pre-commit hooks: `ruff check && mypy src/`
18
+
19
+ ## Testing
20
+
21
+ ```bash
22
+ pytest # Run all tests
23
+ pytest -v # Verbose
24
+ pytest tests/test_cli.py # Single file
25
+ ```
26
+
27
+ ## Pull Requests
28
+
29
+ 1. Create a feature branch from `main`
30
+ 2. Add tests for new functionality
31
+ 3. Ensure all tests pass
32
+ 4. Run `ruff check src/` and `mypy src/`
33
+ 5. Open a PR with a clear description
34
+
35
+ ## Issues
36
+
37
+ - Bug reports: include Python version, OS, and reproduction steps
38
+ - Feature requests: describe the problem you're solving, not your proposed solution
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ObserveCo (Sean Foo)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,188 @@
1
+ Metadata-Version: 2.4
2
+ Name: observeco
3
+ Version: 0.1.0
4
+ Summary: Runtime observability for AI agent systems — pulse, circuit breaker, token compression, dashboard
5
+ Project-URL: Homepage, https://github.com/observeco/observeco
6
+ Project-URL: Documentation, https://github.com/observeco/observeco#readme
7
+ Project-URL: Repository, https://github.com/observeco/observeco
8
+ Author-email: Sean Foo <sean@observeco.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Topic :: System :: Networking :: Monitoring
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: fastapi>=0.110
22
+ Requires-Dist: httpx>=0.27
23
+ Requires-Dist: platformdirs>=4
24
+ Requires-Dist: rich>=13
25
+ Requires-Dist: typer>=0.9
26
+ Requires-Dist: uvicorn[standard]>=0.27
27
+ Provides-Extra: dashboard
28
+ Requires-Dist: jinja2>=3.1; extra == 'dashboard'
29
+ Requires-Dist: python-multipart>=0.0.9; extra == 'dashboard'
30
+ Provides-Extra: dev
31
+ Requires-Dist: mypy>=1.0; extra == 'dev'
32
+ Requires-Dist: pytest-cov>=4; extra == 'dev'
33
+ Requires-Dist: pytest>=7; extra == 'dev'
34
+ Requires-Dist: ruff>=0.3; extra == 'dev'
35
+ Provides-Extra: graph
36
+ Requires-Dist: tree-sitter-python>=0.25; extra == 'graph'
37
+ Requires-Dist: tree-sitter>=0.25; extra == 'graph'
38
+ Provides-Extra: watch
39
+ Requires-Dist: watchdog>=4; extra == 'watch'
40
+ Description-Content-Type: text/markdown
41
+
42
+ # ObserveCo
43
+
44
+ > Runtime observability for your AI agents — built for Hermes, works with anything.
45
+ > Know if your agents are alive, what's in their context, and when something breaks — all from a single `pip install`.
46
+
47
+ ```bash
48
+ pip install observeco[dashboard] && observeco dashboard
49
+ ```
50
+
51
+ <img src="assets/terminal-demo.svg" alt="observeco terminal demo showing pulse check and chisel trim" width="800">
52
+
53
+ <div align="center">
54
+
55
+ [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
56
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)](pyproject.toml)
57
+ [![CI](https://github.com/observeco/observeco/actions/workflows/ci.yml/badge.svg)](https://github.com/observeco/observeco/actions/workflows/ci.yml)
58
+ [![PyPI](https://img.shields.io/pypi/v/observeco)](https://pypi.org/project/observeco/)
59
+ [![GitHub stars](https://img.shields.io/github/stars/observeco/observeco?style=social)](https://github.com/observeco/observeco)
60
+
61
+ </div>
62
+
63
+ ---
64
+
65
+ ## The Dogfood Story
66
+
67
+ We run 7 autonomous agents on an M4 Mac Mini — Hermes, Kepler, Hound, Dreamer, Aleph, PA, and an orchestrator. They communicate via ACPS signals, trigger on fswatch, get scheduled via cron, and their system prompts were growing 15% week-over-week with nobody watching. So we built ObserveCo.
68
+
69
+ We also run Kepler as an OpenClaw agent — persistent, file-driven, with MEMORY.md tracking and dynamic skill loading. Its context was bloating from a different source: memory accumulation, not prompt composition. So we built ClawForge — intent-aware loading and memory hygiene, designed for OpenClaw's architecture.
70
+
71
+ Two frameworks, two optimizers, one dashboard.
72
+
73
+ ---
74
+
75
+ ## Features
76
+
77
+ | Command | What it does |
78
+ |---------|-------------|
79
+ | `observeco pulse check` | Agent liveness — alive/dead/error per agent, zero config for Hermes users |
80
+ | `observeco pulse circuit` | N-failure breaker with auto-cooldown and manual reset |
81
+ | `observeco chisel trim` | System prompt compression with per-component token breakdown |
82
+ | `observeco chisel drift` | 7-day rolling token drift trend per component per agent |
83
+ | `observeco clawforge profile` | Context profiler for OpenClaw: MEMORY.md size, skill count, workspace bloat |
84
+ | `observeco clawforge load` | Intent-aware classifier — dry-run which sources would load per message |
85
+ | `observeco clawforge garden` | Memory hygiene — find duplicates, contradictions, stale entries |
86
+ | `observeco dashboard` | Local web UI: fleet health, token profiles, error timeline, memory debt score |
87
+
88
+ All data local. No cloud. No telemetry.
89
+
90
+ ---
91
+
92
+ ## Quick Start
93
+
94
+ ```bash
95
+ pip install observeco
96
+
97
+ # Check your agent fleet health
98
+ observeco pulse check
99
+
100
+ # See circuit breaker state
101
+ observeco pulse circuit
102
+
103
+ # Compress a system prompt
104
+ echo "Your long system prompt here with tool definitions" | observeco chisel trim
105
+
106
+ # Profile an OpenClaw agent's context
107
+ observeco clawforge profile
108
+
109
+ # Test the intent-aware loader
110
+ observeco clawforge load --probe
111
+
112
+ # Launch the dashboard
113
+ observeco dashboard
114
+ ```
115
+
116
+ ---
117
+
118
+ ## Why ObserveCo?
119
+
120
+ | Instead of... | ObserveCo gives you |
121
+ |---------------|-------------------|
122
+ | **Datadog** ($15+/host/mo, cloud-only) | `pip install`, local-first, free, understands tokens + memory debt + circuit breakers |
123
+ | **Grafana + Prometheus** (2-hour setup, no context concept) | 60 seconds to first health data, agent-aware dashboards |
124
+ | **LangSmith** (LangChain-only, $59/mo) | Framework-agnostic, open source, works offline |
125
+ | **Custom shell scripts** (no dashboard, no trends, no alerts) | Dashboard, drift tracking, circuit breakers, memory hygiene |
126
+ | **Nothing** (failing silently) | You'll know when your agents are sick, bloated, or broken |
127
+
128
+ ---
129
+
130
+ ## Supported Frameworks
131
+
132
+ | Framework | pulse check | pulse circuit | chisel trim | chisel drift | clawforge | Dashboard |
133
+ |-----------|:-----------:|:-------------:|:-----------:|:------------:|:---------:|:---------:|
134
+ | **Hermes** | ✅ Auto | ✅ | ✅ | ✅ | ⬜ | ✅ Full |
135
+ | **OpenClaw** | ✅ (health endpoint) | ◐ (no native circuit) | ⬜ | ⬜ | ✅ v1 | ✅ ~85% |
136
+ | **Ollama** | ✅ (health endpoint) | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
137
+ | **LangChain/LangGraph** | ◐ | ◐ | ⬜ | ⬜ | ⬜ | ✅ Basic |
138
+ | **CrewAI** | ◐ | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
139
+ | **Custom/Any** | ◐ (if health endpoint) | ◐ | ◐ (stdin pipe) | ⬜ | ⬜ | ✅ Basic |
140
+
141
+ ✅ = Auto-detect & works ◐ = Works if you have a health endpoint/piped input ⬜ = v2 feature
142
+
143
+ ---
144
+
145
+ ## Architecture
146
+
147
+ ```
148
+ pip install observeco
149
+ ├── pulse check — agent liveness heartbeat
150
+ ├── pulse circuit — N-failure trip → auto-block → cooldown
151
+ ├── chisel trim — system prompt compression (Hermes — token savings)
152
+ ├── chisel drift — token allocation diff over time (Hermes)
153
+ ├── clawforge profile — context profiler (OpenClaw — MEMORY.md, skills, workspace)
154
+ ├── clawforge load — intent-aware context loader (OpenClaw — ContextEngine hook)
155
+ ├── clawforge garden — memory hygiene agent (OpenClaw — dedup, archive, flag)
156
+ └── observeco dashboard — local web UI, ships with library
157
+ ```
158
+
159
+ - **Storage:** Local SQLite (`~/.observeco/pulse.db`) — zero setup, ships with Python
160
+ - **Web server:** FastAPI + htmx — no build step, no npm, ships with the CLI
161
+ - **CLI:** Typer — beautiful `--help`, shell completion, rich output
162
+
163
+ ---
164
+
165
+ ## Roadmap
166
+
167
+ - [x] `pulse check` — agent liveness
168
+ - [x] `pulse circuit` — circuit breaker
169
+ - [x] `chisel trim` — token compression
170
+ - [x] `chisel drift` — token diff over time
171
+ - [x] `clawforge profile` — context profiler
172
+ - [x] `clawforge load` — intent-aware classifier
173
+ - [x] `clawforge garden` — memory hygiene
174
+ - [x] Dashboard — fleet view, token profiles, error timeline
175
+ - [x] Stripe billing — Solo ($9/mo) + Team ($49/mo)
176
+ - [ ] Framework adapters for LangChain, CrewAI, AutoGen
177
+ - [ ] Push notifications (Pro)
178
+ - [ ] Multi-host fleet monitoring
179
+
180
+ ---
181
+
182
+ ## Contributing
183
+
184
+ See [CONTRIBUTING.md](CONTRIBUTING.md). First-time contributors welcome — look for "good first issue" labels.
185
+
186
+ ---
187
+
188
+ Built with ❤️ for the AI agent community. MIT licensed.
@@ -0,0 +1,147 @@
1
+ # ObserveCo
2
+
3
+ > Runtime observability for your AI agents — built for Hermes, works with anything.
4
+ > Know if your agents are alive, what's in their context, and when something breaks — all from a single `pip install`.
5
+
6
+ ```bash
7
+ pip install observeco[dashboard] && observeco dashboard
8
+ ```
9
+
10
+ <img src="assets/terminal-demo.svg" alt="observeco terminal demo showing pulse check and chisel trim" width="800">
11
+
12
+ <div align="center">
13
+
14
+ [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
15
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)](pyproject.toml)
16
+ [![CI](https://github.com/observeco/observeco/actions/workflows/ci.yml/badge.svg)](https://github.com/observeco/observeco/actions/workflows/ci.yml)
17
+ [![PyPI](https://img.shields.io/pypi/v/observeco)](https://pypi.org/project/observeco/)
18
+ [![GitHub stars](https://img.shields.io/github/stars/observeco/observeco?style=social)](https://github.com/observeco/observeco)
19
+
20
+ </div>
21
+
22
+ ---
23
+
24
+ ## The Dogfood Story
25
+
26
+ We run 7 autonomous agents on an M4 Mac Mini — Hermes, Kepler, Hound, Dreamer, Aleph, PA, and an orchestrator. They communicate via ACPS signals, trigger on fswatch, get scheduled via cron, and their system prompts were growing 15% week-over-week with nobody watching. So we built ObserveCo.
27
+
28
+ We also run Kepler as an OpenClaw agent — persistent, file-driven, with MEMORY.md tracking and dynamic skill loading. Its context was bloating from a different source: memory accumulation, not prompt composition. So we built ClawForge — intent-aware loading and memory hygiene, designed for OpenClaw's architecture.
29
+
30
+ Two frameworks, two optimizers, one dashboard.
31
+
32
+ ---
33
+
34
+ ## Features
35
+
36
+ | Command | What it does |
37
+ |---------|-------------|
38
+ | `observeco pulse check` | Agent liveness — alive/dead/error per agent, zero config for Hermes users |
39
+ | `observeco pulse circuit` | N-failure breaker with auto-cooldown and manual reset |
40
+ | `observeco chisel trim` | System prompt compression with per-component token breakdown |
41
+ | `observeco chisel drift` | 7-day rolling token drift trend per component per agent |
42
+ | `observeco clawforge profile` | Context profiler for OpenClaw: MEMORY.md size, skill count, workspace bloat |
43
+ | `observeco clawforge load` | Intent-aware classifier — dry-run which sources would load per message |
44
+ | `observeco clawforge garden` | Memory hygiene — find duplicates, contradictions, stale entries |
45
+ | `observeco dashboard` | Local web UI: fleet health, token profiles, error timeline, memory debt score |
46
+
47
+ All data local. No cloud. No telemetry.
48
+
49
+ ---
50
+
51
+ ## Quick Start
52
+
53
+ ```bash
54
+ pip install observeco
55
+
56
+ # Check your agent fleet health
57
+ observeco pulse check
58
+
59
+ # See circuit breaker state
60
+ observeco pulse circuit
61
+
62
+ # Compress a system prompt
63
+ echo "Your long system prompt here with tool definitions" | observeco chisel trim
64
+
65
+ # Profile an OpenClaw agent's context
66
+ observeco clawforge profile
67
+
68
+ # Test the intent-aware loader
69
+ observeco clawforge load --probe
70
+
71
+ # Launch the dashboard
72
+ observeco dashboard
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Why ObserveCo?
78
+
79
+ | Instead of... | ObserveCo gives you |
80
+ |---------------|-------------------|
81
+ | **Datadog** ($15+/host/mo, cloud-only) | `pip install`, local-first, free, understands tokens + memory debt + circuit breakers |
82
+ | **Grafana + Prometheus** (2-hour setup, no context concept) | 60 seconds to first health data, agent-aware dashboards |
83
+ | **LangSmith** (LangChain-only, $59/mo) | Framework-agnostic, open source, works offline |
84
+ | **Custom shell scripts** (no dashboard, no trends, no alerts) | Dashboard, drift tracking, circuit breakers, memory hygiene |
85
+ | **Nothing** (failing silently) | You'll know when your agents are sick, bloated, or broken |
86
+
87
+ ---
88
+
89
+ ## Supported Frameworks
90
+
91
+ | Framework | pulse check | pulse circuit | chisel trim | chisel drift | clawforge | Dashboard |
92
+ |-----------|:-----------:|:-------------:|:-----------:|:------------:|:---------:|:---------:|
93
+ | **Hermes** | ✅ Auto | ✅ | ✅ | ✅ | ⬜ | ✅ Full |
94
+ | **OpenClaw** | ✅ (health endpoint) | ◐ (no native circuit) | ⬜ | ⬜ | ✅ v1 | ✅ ~85% |
95
+ | **Ollama** | ✅ (health endpoint) | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
96
+ | **LangChain/LangGraph** | ◐ | ◐ | ⬜ | ⬜ | ⬜ | ✅ Basic |
97
+ | **CrewAI** | ◐ | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
98
+ | **Custom/Any** | ◐ (if health endpoint) | ◐ | ◐ (stdin pipe) | ⬜ | ⬜ | ✅ Basic |
99
+
100
+ ✅ = Auto-detect & works ◐ = Works if you have a health endpoint/piped input ⬜ = v2 feature
101
+
102
+ ---
103
+
104
+ ## Architecture
105
+
106
+ ```
107
+ pip install observeco
108
+ ├── pulse check — agent liveness heartbeat
109
+ ├── pulse circuit — N-failure trip → auto-block → cooldown
110
+ ├── chisel trim — system prompt compression (Hermes — token savings)
111
+ ├── chisel drift — token allocation diff over time (Hermes)
112
+ ├── clawforge profile — context profiler (OpenClaw — MEMORY.md, skills, workspace)
113
+ ├── clawforge load — intent-aware context loader (OpenClaw — ContextEngine hook)
114
+ ├── clawforge garden — memory hygiene agent (OpenClaw — dedup, archive, flag)
115
+ └── observeco dashboard — local web UI, ships with library
116
+ ```
117
+
118
+ - **Storage:** Local SQLite (`~/.observeco/pulse.db`) — zero setup, ships with Python
119
+ - **Web server:** FastAPI + htmx — no build step, no npm, ships with the CLI
120
+ - **CLI:** Typer — beautiful `--help`, shell completion, rich output
121
+
122
+ ---
123
+
124
+ ## Roadmap
125
+
126
+ - [x] `pulse check` — agent liveness
127
+ - [x] `pulse circuit` — circuit breaker
128
+ - [x] `chisel trim` — token compression
129
+ - [x] `chisel drift` — token diff over time
130
+ - [x] `clawforge profile` — context profiler
131
+ - [x] `clawforge load` — intent-aware classifier
132
+ - [x] `clawforge garden` — memory hygiene
133
+ - [x] Dashboard — fleet view, token profiles, error timeline
134
+ - [x] Stripe billing — Solo ($9/mo) + Team ($49/mo)
135
+ - [ ] Framework adapters for LangChain, CrewAI, AutoGen
136
+ - [ ] Push notifications (Pro)
137
+ - [ ] Multi-host fleet monitoring
138
+
139
+ ---
140
+
141
+ ## Contributing
142
+
143
+ See [CONTRIBUTING.md](CONTRIBUTING.md). First-time contributors welcome — look for "good first issue" labels.
144
+
145
+ ---
146
+
147
+ Built with ❤️ for the AI agent community. MIT licensed.
@@ -0,0 +1,88 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" width="1280" height="640">
2
+ <defs>
3
+ <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
4
+ <stop offset="0%" style="stop-color:#0F172A;stop-opacity:1" />
5
+ <stop offset="100%" style="stop-color:#1E293B;stop-opacity:1" />
6
+ </linearGradient>
7
+ <linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="100%">
8
+ <stop offset="0%" style="stop-color:#0EA5E9;stop-opacity:1" />
9
+ <stop offset="100%" style="stop-color:#14B8A6;stop-opacity:1" />
10
+ </linearGradient>
11
+ </defs>
12
+
13
+ <!-- Background -->
14
+ <rect width="1280" height="640" fill="url(#bg)"/>
15
+
16
+ <!-- Decorative grid dots -->
17
+ <g fill="#334155" opacity="0.3">
18
+ <circle cx="100" cy="100" r="1"/><circle cx="200" cy="100" r="1"/>
19
+ <circle cx="300" cy="100" r="1"/><circle cx="400" cy="100" r="1"/>
20
+ <circle cx="500" cy="100" r="1"/><circle cx="600" cy="100" r="1"/>
21
+ <circle cx="700" cy="100" r="1"/><circle cx="800" cy="100" r="1"/>
22
+ <circle cx="900" cy="100" r="1"/><circle cx="1000" cy="100" r="1"/>
23
+ <circle cx="1100" cy="100" r="1"/><circle cx="1200" cy="100" r="1"/>
24
+ </g>
25
+
26
+ <!-- Logo icon -->
27
+ <g transform="translate(60, 50)">
28
+ <circle cx="32" cy="32" r="28" fill="none" stroke="url(#accent)" stroke-width="1.5" opacity="0.4"/>
29
+ <polyline points="4,32 14,32 18,20 22,40 26,18 30,44 34,22 38,32 42,22 46,44 50,18 54,40 58,20 60,32"
30
+ fill="none" stroke="url(#accent)" stroke-width="3" stroke-linecap="round"/>
31
+ <circle cx="18" cy="20" r="2" fill="#0EA5E9" opacity="0.7"/>
32
+ <circle cx="26" cy="18" r="2" fill="#14B8A6" opacity="0.7"/>
33
+ <circle cx="34" cy="22" r="2" fill="#06B6D4" opacity="0.7"/>
34
+ <circle cx="42" cy="22" r="2" fill="#0EA5E9" opacity="0.7"/>
35
+ <circle cx="50" cy="18" r="2" fill="#14B8A6" opacity="0.7"/>
36
+ </g>
37
+
38
+ <!-- Title -->
39
+ <text x="120" y="110" font-family="system-ui, -apple-system, sans-serif" font-size="56" font-weight="700" fill="#FFFFFF">
40
+ ObserveCo
41
+ <tspan fill="url(#accent" font-size="56">.</tspan>
42
+ </text>
43
+
44
+ <!-- Tagline -->
45
+ <text x="120" y="160" font-family="system-ui, -apple-system, sans-serif" font-size="22" fill="#94A3B8">
46
+ Runtime observability for your AI agents
47
+ </text>
48
+
49
+ <!-- Terminal mockup area -->
50
+ <rect x="80" y="200" width="1120" height="340" rx="12" fill="#1E293B" stroke="#334155" stroke-width="1.5"/>
51
+
52
+ <!-- Terminal window dots -->
53
+ <circle cx="110" cy="228" r="6" fill="#EF4444"/>
54
+ <circle cx="135" cy="228" r="6" fill="#EAB308"/>
55
+ <circle cx="160" cy="228" r="6" fill="#22C55E"/>
56
+
57
+ <!-- Terminal title -->
58
+ <text x="640" y="235" font-family="monospace" font-size="14" fill="#64748B" text-anchor="middle">observeco pulse check</text>
59
+
60
+ <!-- Terminal lines -->
61
+ <!-- Line 1: command -->
62
+ <text x="110" y="280" font-family="monospace" font-size="16" fill="#38BDF8">$ observeco pulse check</text>
63
+
64
+ <!-- Line 2: output - hermes-triage -->
65
+ <text x="130" y="310" font-family="monospace" font-size="15" fill="#4ADE80">🟢 hermes-triage</text>
66
+ <text x="500" y="310" font-family="monospace" font-size="15" fill="#64748B">12s ago · Tokens: 4.2K · Drift: +3%</text>
67
+
68
+ <!-- Line 3: output - pragma -->
69
+ <text x="130" y="340" font-family="monospace" font-size="15" fill="#4ADE80">🟢 pragma</text>
70
+ <text x="500" y="340" font-family="monospace" font-size="15" fill="#64748B">8s ago · Tokens: 2.1K · Drift: -1%</text>
71
+
72
+ <!-- Line 4: output - kepler -->
73
+ <text x="130" y="370" font-family="monospace" font-size="15" fill="#FBBF24">🟡 kepler</text>
74
+ <text x="500" y="370" font-family="monospace" font-size="15" fill="#64748B">3m ago · Tokens: 8.1K · Drift: +18%</text>
75
+
76
+ <!-- Line 5: output - hermes-dev -->
77
+ <text x="130" y="400" font-family="monospace" font-size="15" fill="#F87171">🔴 hermes-dev</text>
78
+ <text x="500" y="400" font-family="monospace" font-size="15" fill="#64748B">45s ago · Circuit: tripped</text>
79
+
80
+ <!-- Cursor blink -->
81
+ <text x="110" y="440" font-family="monospace" font-size="16" fill="#38BDF8">$</text>
82
+ <rect x="125" y="424" width="10" height="18" fill="#38BDF8" opacity="0.8"/>
83
+
84
+ <!-- Bottom: pip install -->
85
+ <rect x="80" y="560" width="1120" height="50" rx="8" fill="#0F172A" stroke="#334155" stroke-width="1"/>
86
+ <text x="110" y="593" font-family="monospace" font-size="18" fill="#A78BFA">$ pip install observeco[dashboard]</text>
87
+ <text x="600" y="593" font-family="monospace" font-size="18" fill="#22C55E">✨ Done in 12s</text>
88
+ </svg>