{"id":50718159,"url":"https://github.com/BlazeUp-AI/Observal","last_synced_at":"2026-06-26T22:00:36.921Z","repository":{"id":348451580,"uuid":"1196352488","full_name":"BlazeUp-AI/Observal","owner":"BlazeUp-AI","description":"Observal is a local registry and analytics platform for your AI components.  Setup Observal, define the scope and share your Skills, MCPs and Agents.","archived":false,"fork":false,"pushed_at":"2026-06-22T15:18:52.000Z","size":22320,"stargazers_count":2112,"open_issues_count":285,"forks_count":453,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-06-22T16:25:19.928Z","etag":null,"topics":["agents","analytics","antigravity","claude-code","cli-tool","codex","cursor","cursor-ai","insights","kiro","large-language-models","mcp","open-source","pi","playground","registry","self-hosted","skills"],"latest_commit_sha":null,"homepage":"https://observal.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlazeUp-AI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2026-03-30T16:05:36.000Z","updated_at":"2026-06-22T11:43:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"4fb333bf-8ed9-4e6a-b30b-00e50a1f9ca3","html_url":"https://github.com/BlazeUp-AI/Observal","commit_stats":null,"previous_names":["blazeup-ai/observal"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/BlazeUp-AI/Observal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlazeUp-AI%2FObserval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlazeUp-AI%2FObserval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlazeUp-AI%2FObserval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlazeUp-AI%2FObserval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlazeUp-AI","download_url":"https://codeload.github.com/BlazeUp-AI/Observal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlazeUp-AI%2FObserval/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34834415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","analytics","antigravity","claude-code","cli-tool","codex","cursor","cursor-ai","insights","kiro","large-language-models","mcp","open-source","pi","playground","registry","self-hosted","skills"],"created_at":"2026-06-09T21:00:25.962Z","updated_at":"2026-06-26T22:00:36.910Z","avatar_url":"https://github.com/BlazeUp-AI.png","language":"Python","funding_links":[],"categories":["*Ops for AI"],"sub_categories":["LLMOps"],"readme":"\u003c!-- SPDX-FileCopyrightText: 2026 Ai-chan-0411 \u003caoikabu12@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Apoorv Garg \u003capoorvgarg.21@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Aryan Iyappan \u003caryaniyappan2006@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Subramania Raja \u003cdhanpraja231@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Hari Srinivasan \u003charisrini21@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Hemalatha Madeswaran \u003chemalathamadeswaran@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Kaushik Kumar \u003ckaushikrjpm10@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Lokesh Selvam \u003clokeshselvam7025@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Naraen Rammoorthi \u003cnaraen13@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Shaan Narendran \u003cshaannaren06@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Shreem Seth \u003cshreemseth26@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 DoomsCoder \u003cvedantkakade05@gmail.com\u003e --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2026 Vishnu Muthiah \u003cvishnu.muthiah04@gmail.com\u003e --\u003e\n\u003c!-- SPDX-License-Identifier: AGPL-3.0-only --\u003e\n\n\u003cpre\u003e\n ██████╗ ██████╗ ███████╗███████╗██████╗ ██╗   ██╗ █████╗ ██╗\n██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██╔══██╗██║\n██║   ██║██████╔╝███████╗█████╗  ██████╔╝██║   ██║███████║██║\n██║   ██║██╔══██╗╚════██║██╔══╝  ██╔══██╗╚██╗ ██╔╝██╔══██║██║\n╚██████╔╝██████╔╝███████║███████╗██║  ██║ ╚████╔╝ ██║  ██║███████╗\n ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚══════╝\n\u003c/pre\u003e\n\n**A registry and insight platform for portable AI coding agents. Define context once, install it across tools, and learn what works.**\n\n\u003cp\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.11+-3776ab?style=flat-square\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003ca href=\"https://pypi.org/project/observal-cli/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/observal-cli?style=flat-square\u0026logo=pypi\u0026logoColor=white\u0026label=pypi\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/BlazeUp-AI/Observal\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/github/BlazeUp-AI/Observal?style=flat-square\u0026logo=codecov\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/BlazeUp-AI/Observal/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/BlazeUp-AI/Observal?style=flat-square\u0026logo=github\" alt=\"Contributors\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.observal.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/discord-chat-5865f2?style=flat-square\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/orgs/BlazeUp-AI/packages?repo_name=Observal\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Haz3-jolt/b28aba6d0efebb0b430d43c8068feb91/raw/ghcr-pulls.json\u0026style=flat-square\" alt=\"GHCR pulls\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e If you find Observal useful, please consider giving it a star. It helps others discover the project and keeps development going.\n\n---\n\n## What Observal is for\n\nObserval is for teams doing context engineering across AI coding tools. If your organization maintains Skills, AGENTS files, MCP servers, hooks, prompts, sandboxes, or subagent definitions, Observal gives you one place to package them into versioned agents, publish them to a registry, and install them into the harness or harness your developers use.\n\nDefine an agent once. Observal renders the right configuration for Claude Code, Cursor, Kiro, Pi, Copilot, Codex, OpenCode, and other supported tools. As teams use those agents, Observal turns real usage into insights about which prompts, skills, tools, and policies are helping.\n\n### Why teams use Observal\n\n- **Package context into reusable agents:** Bundle Skills, MCP servers, hooks, prompts, sandboxes, and policy into one versioned unit.\n- **Run a governed registry:** Review submissions, approve internal agents, inspect version diffs, and give developers one trusted place to install from.\n- **Render across coding tools:** Generate the correct config for each supported harness instead of maintaining separate setup instructions for every harness.\n- **Learn what works:** Use real adoption and session data to find which agents, tools, prompts, and workflows are helping teams.\n- **Replay sessions when needed:** Use traces as evidence for debugging, review, audits, and deeper analysis without making observability the main workflow.\n\n---\n\n## Supported harnesses\n\n| harness |\n|-----|\n| Claude Code |\n| Kiro |\n| Cursor |\n| Pi |\n| Copilot (CLI \u0026 VS Code Extension) |\n| Codex |\n| OpenCode |\n| Antigravity CLI |\n\nOne command to install any agent into any supported harness. The config files are generated per-harness automatically.\n\n---\n\n## Quick Start\n\nObserval has two parts: a **server** (API + web UI + databases) you self-host, and a **CLI** you install on each developer machine.\n\n### 1. Deploy the server\n\n**One-line install** (requires Docker Engine ≥ 24.0 with Compose v2):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash\n```\n\nThis downloads a Docker Compose package, runs guided setup (domain, secrets, ports), pulls container images from GHCR, and starts the full stack (API, web UI, PostgreSQL, ClickHouse, Redis, worker, load balancer, Prometheus, Grafana).\n\n**From source** (for contributors):\n\n```bash\ngit clone https://github.com/BlazeUp-AI/Observal.git \u0026\u0026 cd Observal\ncp .env.example .env\nmake up\n```\n\n### 2. Install the CLI\n\n**Standalone binary** (no Python required):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install.sh | bash\n```\n\n**Python** (3.11+):\n\n```bash\nuv tool install observal-cli\n# or: pipx install observal-cli\n```\n\n### 3. Connect your harness\n\n```bash\nobserval auth login\nobserval doctor --patch\n```\n\nThis authenticates with your server, detects your harness, installs telemetry hooks, starts capturing sessions automatically, and prepares it for agent installs and registry commands.\n\nOnce logged in, run `/observal` inside your harness and it takes the wheel. Pull agents, submit components, browse the registry, run diagnostics:\n\n```\n/observal pull security-auditor\n/observal scan\n/observal doctor\n```\n\nOr just tell your agent what you want and it figures out the right commands.\n\n---\n\n## How Observal works\n\n### Agents are portable context packages\n\nAn agent bundles 5 component types into a single installable package: **MCP servers**, **skills**, **hooks**, **prompts**, and **sandboxes**. You define the agent once, publish it to the registry, and Observal generates the right config files for whichever supported harness or harness the user runs.\n\n```bash\nobserval pull security-auditor --harness pi\n```\n\n### The registry is the distribution layer\n\nBrowse published agents, see which harnesses they support, check download counts and ratings, and install with one command. Admins review submissions before they go live. Version diffs show exactly what changed between releases, so teams can safely evolve shared context.\n\n### Insights show what is helping\n\nObserval turns real usage into reports about which agents, prompts, tools, and workflows are working or getting in the way. Use those insights to improve shared context instead of guessing from anecdotes.\n\n### Session traces provide the evidence\n\nWhen you need to debug, audit, or understand a result, Observal can replay the full coding session: user prompts, thinking blocks, assistant responses, and tool calls with their inputs and outputs. The traces support registry and insight workflows rather than defining the product.\n\n---\n\n## Agent Registry\n\n**Browse, search, and install agents with harness compatibility badges:**\n\n![Agent registry with grid view](docs/img/registry.png)\n\n**Build agents visually with live config preview for every harness:**\n\n![Agent Builder with preview panel](docs/img/builder.png)\n\n**Components library: MCPs, Skills, Hooks, Prompts, Sandboxes:**\n\n![Component registry showing MCP servers](docs/img/component_registry.png)\n\n---\n\n## Agent Insights\n\n**AI-powered insight reports** analyze usage patterns across all sessions, what's working, what's hindering, and quick wins. Powered by [LiteLLM](https://docs.litellm.ai/docs/providers), works with any provider (Anthropic, OpenAI, Bedrock, Gemini, Azure, Ollama).\n\n![Insight report with What's Working, What's Hindering, Quick Wins](docs/img/insights.png)\n\nSee [Insights LLM Setup](docs/insights-setup.md) for configuration.\n\n---\n\n## Session Replay\n\n**Full session overview with token counts, models, tools, and turn-by-turn timeline:**\n\n![Session detail showing tokens, tools, models, and turns](docs/img/ses1.png)\n\n**Every turn captured: user prompt, tool calls, thinking block, assistant response:**\n\n![Turn expanded showing user prompt, thinking, and response](docs/img/complete_capture_thinking_response.png)\n\n**Drill into any span to see exact tool inputs and outputs:**\n\n![Span detail showing bash command input and full output](docs/img/span.png)\n\n---\n\n## Review and Governance\n\n**Admin review queue with full prompt inspection and approve/reject:**\n\n![Review queue with agent detail](docs/img/review.png)\n\n**Version diffs show exactly what changed between releases:**\n\n![Side-by-side diff of v1.0.0 vs v2.0.0](docs/img/review-diff.png)\n\n**Leaderboard tracks top agents and components by downloads:**\n\n![Leaderboard with rankings](docs/img/leaderboard.png)\n\n---\n\n## Enterprise Edition\n\nSource-available under a separate license. Activated with a signed JWT key. Core never imports from `ee/`, the open-source edition is fully functional without it.\n\nEnterprise adds:\n\n- **Audit trail/logs** with parameterized search and CSV export\n- **SAML SSO** and **SCIM provisioning**\n- **Executive dashboard** for org-wide agent performance\n\n**Audit log with parameterized search:**\n\n![Audit log with PHI sensitivity badges and chain hashes](docs/img/audit_logging.png)\n\nThe server and CLI are the same package for all editions. Enterprise features activate at runtime when a valid license key is present:\n\n```bash\n# Pass the key during server install\ncurl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash -s -- --license-key YOUR_KEY\n\n# Or add it later to your .env\necho 'OBSERVAL_LICENSE_KEY=your.key' \u003e\u003e .env\nmake rebuild\n```\n\n---\n\n## Documentation\n\nFull docs at **[docs.observal.io](https://docs.observal.io/)**\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | Next.js 16, React 19, Tailwind CSS 4, shadcn/ui |\n| Backend | Python 3.11+, FastAPI, Strawberry GraphQL |\n| Databases | PostgreSQL 16 (registry), ClickHouse (telemetry) |\n| Queue | Redis + arq |\n| CLI | Python, Typer, Rich |\n| Telemetry | Session hooks, stdio shims, push-based ingest |\n| Deployment | Docker Compose (10 services) |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). The short version:\n\n1. Fork and clone\n2. `make hooks` to install pre-commit hooks\n3. Create a feature branch\n4. Run `make lint` and `make test`\n5. Open a PR\n\nSee [AGENTS.md](AGENTS.md) for internal codebase context.\n\n## Community\n\n[GitHub Discussions](https://github.com/BlazeUp-AI/Observal/discussions) for questions and ideas. [Discord](https://discord.observal.io) for chat. Open Issues for confirmed bugs.\n\n## Reporting Issues\n\n```bash\nobserval support bundle\n```\n\nProduces a redacted diagnostic archive. Review before sharing: `observal support inspect observal-support-*.tar.gz`\n\nFor live debugging, Observal uses loguru-based dev logging (internally called \"optic\"). Stream logs with:\n\n```bash\nobserval logs\n```\n\nLogs are written to `~/.observal/logs/dev.log` and include structured context for every request, background job, and telemetry event.\n\n## Security\n\nReport vulnerabilities via [GitHub Private Vulnerability Reporting](https://github.com/BlazeUp-AI/Observal/security/advisories) or email contact@blazeup.app. Do not open a public issue. See [SECURITY.md](SECURITY.md).\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=BlazeUp-AI%2FObserval\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=BlazeUp-AI/Observal\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=BlazeUp-AI/Observal\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=BlazeUp-AI/Observal\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\nGNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBlazeUp-AI%2FObserval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBlazeUp-AI%2FObserval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBlazeUp-AI%2FObserval/lists"}