Development
Plugin
observal
Observal is a local registry and analytics platform for your AI components. Setup Observal, define the scope and share your Skills, MCPs and Agents.
Plugin Signal78/100Solid
maintained100
capable41
documented100
adopted71
Install
$ npx -y skills add Observal/Observal --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
What's inside
Skills
6/observal-adminObserval admin operations including user management, server settings, submission review queue, security events, audit logs, and SSO configuration. Use when the user needs to manage users, approve or reject submissions, view security events, or configure SAML/SCIM./observal-advancedAdvanced Observal operations including session reconciliation, CLI upgrades and downgrades, complete uninstallation, and local fallback mode for offline use. Use when the user wants to reconcile sessions, upgrade or downgrade the CLI, uninstall Observal, or write agent configs/observal-agentsCreate, update, version, and manage Observal agents. Use when the user wants to create a new agent, update an existing one, release a new version, scaffold a YAML project, add components, build, publish, bulk-create, archive, delete, or restore agents./observal-opsView traces, spans, metrics, feedback, telemetry health, and agent insight reports, including suggestions that reuse components already in the registry. Use when the user wants to see traces, check metrics, view top items, submit ratings, diagnose telemetry, or discuss how an/observal-registrySubmit, browse, install, edit, archive, restore, transfer, and version MCPs, skills, hooks, prompts, and sandboxes in the Observal registry, and get components recommended for the current user. Use when the user wants to submit a component, install one, edit a draft, publish a/observalCore Observal CLI operations: pull agents into your harness, scan installed components, diagnose and patch harness configs, authenticate, manage CLI settings, get components recommended for you, and discuss agent insights. Use when the user wants to install an agent, check
README
1Observal is the control plane and system of record for internal AI components
If you find Observal useful, please consider giving it a star. It helps others discover the project and keeps development going.
What is Observal and what does it solve?
Observal is the control plane and system of record for internal AI components. Every tech-forward organization today creates internal Skills, Agents, MCP servers and other AI components to boost productivity. Though the creation of these components has been prolific, the adoption and usage of such components is sparse. Developer/AI users today end up creating their own version of AI components without reusing existing packages.
The cause is largely due to two problems:
-
Lack of a discoverability layer
Organizations store their AI components and agents in siloed github repositories with little to no documentation. Users are not able to locate similar components and this results in multiple developers creating the same/similar components again.
-
Missing feedback loop
Any software where usage patterns are not understood and the principle of user-centric development is violated tends to fade out. Such is the problem with development of MCPs, Skills and Agents. Developers publish and maintain these components with little visibility into how they're actually used. Additionally, AI failures don't trigger static error codes: they hallucinate or provide subtly incorrect answers. This leaves users clueless about what went wrong compounding the feedback problem.
Observal solves this by providing a centralized discovery layer for AI components alongside useful insights into AI usage patterns. It turns silent failures into actionable feedback, ensuring internal AI tools are continuously optimized for the people using them.
Observal supports Claude Code, Cursor, Kiro, Pi, Copilot, Codex, OpenCode, and other tools.
Why teams use Observal
- Package components into reusable agents: Bundle Skills, MCP servers, hooks, prompts, and sandboxes into one versioned unit.
- Run a governed registry: Review submissions, approve internal agents, inspect version diffs, and give developers one trusted place to install from.
- Render across multiple Coding IDE/CLI: Generate the correct config for each supported harness instead of maintaining separate setup instructions for every harness.
- Learn what works: Use real adoption and session data to find which agents, tools, prompts, and workflows are helping teams.
- Replay sessions when needed: Use traces as evidence for debugging, review, audits, and deeper analysis.
Supported harnesses
| harness |
|---|
| Claude Code |
| Kiro |
| Cursor |
| Pi |
| Copilot (CLI & VS Code Extension) |
| Codex |
| OpenCode |
| Antigravity CLI |
| Goose |
One command to install any agent into any supported harness. The config files are generated per-harness automatically.
Quick Start
Observal has two parts: a server (API + web UI + databases) you self-host, and a CLI you install on each developer machine.
1. Deploy the server
One-line install (requires Docker Engine ≥ 24.0 with Compose v2):
curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install-server.sh | bash
This downloads a Docker Compose package, generates operator-owned secret files with restricted container-group access, binds published ports to loopback by default, pulls container images from GHCR, and starts the stack. With a terminal it runs guided setup; without a terminal the same command applies safe defaults automatically.
Deployment docs are linked directly from this README:
- Setup guide: fastest path from zero to a working stack
- Self-hosting overview: deployment models and operator docs
- Production deployment: hardened production topology
- Databases: Postgres, ClickHouse, migrations, retention
- Upgrades: safe upgrade and rollback flow
- Release verification: verify checksums, provenance, and signed tags
- Backup and restore: backup plan before upgrades
From source (for contributors):
git clone https://github.com/Observal/Observal.git && cd Observal
cp .env.example .env
make up
2. Install the CLI
Standalone binary (no Python required):
curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install.sh | bash
Python (3.11+):
uv tool install observal-cli
# or: pipx install observal-cli
3. Connect your harness
observal auth login
observal doctor --patch
This authenticates with your server, detects your harness, installs telemetry hooks, starts capturing sessions automatically, and prepares it for agent installs and registry commands.
Once logged in, run /observal inside your harness and it takes the wheel. Pull agents, submit components, browse the registry, run diagnostics:
/observal pull security-auditor
/observal scan
/observal doctor
Or just tell your agent what you want and it figures out the right commands.
How Observal works
Agents are portable context packages
An 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 the user runs.
observal pull security-auditor --harness pi
The registry is the distribution layer
The registry is where agents live. Admins review submissions, version diffs keep changes auditable, and one command installs an agent into any supported harness.
Insights close the loop
Real usage data flows back as reports: what's helping, what's getting in the way, and where to improve. Session traces provide the underlying evidence for debugging and auditing.
Agent Registry
Browse, search, and install agents with harness compatibility badges:
Build agents visually with live config preview for every harness:
Components library: MCPs, Skills, Hooks, Prompts, Sandboxes:
Agent Insights
AI-powered insight reports analyze usage patterns across all sessions, what's working, what's hindering, and quick wins. Powered by LiteLLM, works with any provider (Anthropic, OpenAI, Bedrock, Gemini, Azure, Ollama).
See Insights LLM Setup for configuration.
Session Replay
Full session overview with token counts, models, tools, and turn-by-turn timeline:
Every turn captured: user prompt, tool calls, thinking block, assistant response:
Drill into any span to see exact tool inputs and outputs:
Review and Governance
Admin review queue with full prompt inspection and approve/reject:
Side-by-side version diffs before approving a new release:
Leaderboard tracks top agents and components by downloads:
Open-source features
Audit logs, SAML SSO, SCIM provisioning, and the executive dashboard are included in the Apache-2.0 distribution.
Audit log with parameterized search:
Documentation
Full docs at docs.observal.io.
Start here for deployment and operations:
| Need | Link |
|---|---|
| Fast local or source setup | SETUP.md |
| Self-hosting overview | docs/self-hosting/README.md |
| Production deployment | docs/self-hosting/production-deploy.md |
| Single-node deployment | docs/self-hosting/single-node-deploy.md |
| Docker Compose setup | docs/self-hosting/docker-compose.md |
| Databases and migrations | docs/self-hosting/databases.md |
| Upgrades | docs/self-hosting/upgrades.md |
| Backup and restore | docs/self-hosting/backup-and-restore.md |
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | Vite 6, React 19, TanStack Router, Tailwind CSS 4, shadcn/ui |
| Backend | Python 3.11+, FastAPI, Strawberry GraphQL |
| Databases | PostgreSQL 16 (registry), ClickHouse (telemetry) |
| Queue | Redis + arq |
| CLI | Python, Typer, Rich |
| Telemetry | Session hooks, local transcript reconciliation, push-based ingest |
| Deployment | Docker Compose (10 services), Kubernetes (Helm) |
Contributing
See CONTRIBUTING.md. The short version:
- Fork and clone
make hooksto install pre-commit hooks- Create a feature branch
- Run
make lintandmake test - Open a PR
See AGENTS.md for internal codebase context.
Community
GitHub Discussions for questions and ideas. Discord for chat. Open Issues for confirmed bugs.
Reporting Issues
observal support bundle
Produces a redacted diagnostic archive. Review before sharing: observal support inspect observal-support-*.tar.gz
For live debugging, Observal uses loguru-based dev logging (internally called "optic"). Stream logs with:
observal logs
Logs are written to ~/.observal/logs/dev.log and include structured context for every request, background job, and telemetry event.
Security
Report vulnerabilities via GitHub Private Vulnerability Reporting or email contact@observal.io. Do not open a public issue. See SECURITY.md.
License
Observal is licensed under the Apache License 2.0. See LICENSE.
File tree
1356Observal/ObservalView on GitHub
.clabot
.coderabbit.yaml
.dockerignore
.editorconfig
.env.example
.gitattributes
.gitbook.yaml
.github/
CODEOWNERS
ISSUE_TEMPLATE/
bug_report_form.yml
config.yml
feature_request.yml
harness_support_quick.yml
harness_support.md
pull_request_template.md
release-notes.md
secret_scanning.yml
vex/
observal.vex.json
workflows/
badge-ghcr-pulls.yml
ci.yml
codeql.yml
dependency-review.yml
deploy.yml
e2e-frontend.yml
gitleaks.yml
pr-labels.yml
release.yml
sbom.yml
scorecard.yml
stale.yml
take-command.yml
terraform.yml
update-homebrew-tap.yml
.gitignore
.gitleaks.toml
.pre-commit-config.yaml
.release.toml
.reuse/
license-policy.yml
AGENTS.md
AI_POLICY.md
CHANGELOG.md
CLA.md
CODE_OF_CONDUCT.md
codecov.yml
CONTRIBUTING.md
docker/
clickhouse/
config.d/
listen.xml
memory.xml
users.d/
memory.xml
docker-compose.dev.yml
docker-compose.observability.yml
docker-compose.production.yml
docker-compose.yml
Dockerfile.api
Dockerfile.web
entrypoint.sh
nginx-azure.conf
nginx-spa-ecs.conf
nginx-spa.conf
nginx.conf
nginx.dev.conf
nginx.production.conf
server-package/
docker-compose.observability.yml
docker-compose.yml
env.template
prometheus.yml
setup.sh
docs/
.gitbook/
assets/
insights.png
logo-light.svg
logo.svg
adding-a-harness.md
cli/
admin.md
agent.md
auth.md
component.md
config.md
doctor.md
migrate.md
models.md
ops.md
prompt.md
pull.md
README.md
registry.md
scan.md
self.md
server.md
skill.md
support.md
uninstall.md
code-review.md
core-concepts/
README.md
session-tracking.md
DEVELOPMENT_GUIDE.md
e2e-test-checklist.md
getting-started/
installation.md
quickstart.md
hooks.md
img/
audit_logging.png
builder.png
complete_capture_thinking_response.png
component_registry.png
insights.png
leaderboard.png
registry.png
review-diff.png
review.png
ses1.png
span.png
traces.png
insights-config.md
insights-setup.md
integrations/
copilot.md
cursor.md
goose.md
kiro.md
opencode.md
licensing.md
logo-light.svg
logo.svg
README.md
reference/
api-endpoints.md
config-files.md
environment-variables.md
hooks-spec.md
registry-hook-helper.md
registry-mcp-helper.md
registry-sandbox-helper.md
registry-skill-helper.md
sandboxes.md
security/
assurance-case.md
release-verification.md
self-hosting/
authentication.md
aws-terraform.md
backup-and-restore.md
cli-sso.md
configuration.md
data-migration.md
data-retention.md
databases.md
deployment-settings.md
docker-compose.md
gcp-terraform.md
kubernetes-helm.md
miscellaneous.md
observability-settings.md
oidc-setup.md
okta-setup.md
ports-and-volumes.md
production-deploy.md
README.md
releasing.md
requirements.md
resource-tuning.md
saml-settings.md
saml-setup.md
scim-setup.md
single-node-deploy.md
sso-cli.md
token-expiry.md
troubleshooting.md
trusted-proxies.md
upgrades.md
self-observability.md
SUMMARY.md
testing/
Testing_Guide.md
use-cases/
debug-agent-failures.md
observe-mcp-traffic.md
README.md
share-agent-configs.md
team-registry.md
teamspaces.md
fuzz/
_paths.py
_session.py
corpus/
secrets_redactor_fuzzer/
assignments.txt
session_jsonl_fuzzer/
antigravity.jsonl
claude_code.jsonl
codex.jsonl
copilot_cli.jsonl
cursor.jsonl
goose.jsonl
kiro.jsonl
malformed.jsonl
opencode.jsonl
pi.jsonl
support_redaction_fuzzer/
collector_output.txt
dictionaries/
secrets_redactor_fuzzer.dict
session_jsonl_fuzzer.dict
support_redaction_fuzzer.dict
oss-fuzz/
build.sh
Dockerfile
project.yaml
README.md
secrets_redactor_fuzzer.py
session_jsonl_fuzzer.py
session_structure_fuzzer.py
support_redaction_fuzzer.py
grafana/
dashboards/
agent-activity.json
audit-log.json
cost-tracking.json
error-rates.json
performance-resources.json
self-observability.json
session-overview.json
token-usage.json
tool-call-frequency.json
provisioning/
dashboards/
default.yaml
datasources/
clickhouse.yaml
prometheus.yaml
infra/
helm/
artifacthub-repo.yml
observal/
.helmignore
Chart.yaml
README.md
templates/
_helpers.tpl
api-deployment.yaml
api-service.yaml
apidata-pvc.yaml
clickhouse-service.yaml
clickhouse-statefulset.yaml
configmap-clickhouse-config.yaml
configmap-clickhouse-users.yaml
configmap-env.yaml
configmap-web-nginx.yaml
db-service.yaml
db-statefulset.yaml
ingress.yaml
init-job.yaml
NOTES.txt
redis-service.yaml
redis-statefulset.yaml
role.yaml
rolebinding.yaml
secret.yaml
serviceaccount.yaml
web-deployment.yaml
web-service.yaml
worker-deployment.yaml
values.yaml
terraform/
aws/
aws-ec2/
deploy.sh
main.tf
outputs.tf
README.md
terraform.tfvars.example
variables.tf
aws-standard/
alb.tf
data-host.tf
data-user-data.sh.tftpl
ecs-cluster.tf
ecs-instances.tf
ecs-services.tf
ecs-tasks.tf
iam.tf
locals.tf
logs.tf
outputs.tf
README.md
s3.tf
secrets.tf
security.tf
terraform.tfvars.example
variables.tf
versions.tf
vpc.tf
.gitignore
.tflint.hcl
alb.tf
bootstrap/
main.tf
outputs.tf
README.md
variables.tf
versions.tf
clickhouse.tf
deploy.sh
dns.tf
ecs.tf
examples/
byovpc/
main.tf
outputs.tf
README.md
terraform.tfvars.example
variables.tf
minimal/
main.tf
outputs.tf
README.md
terraform.tfvars.example
variables.tf
iam.tf
locals.tf
logs.tf
outputs.tf
postgresql.tf
README.md
redis.tf
s3.tf
secrets.tf
security.tf
terraform.tfvars.example
user-data.sh.tftpl
variables.tf
versions.tf
vpc.tf
azure/
.terraform.lock.hcl
acr.tf
backend.tf
clickhouse.tf
cloud-init.yaml.tftpl
container-apps.tf
examples/
minimal/
.terraform.lock.hcl
main.tf
grafana.tf
locals.tf
log-analytics.tf
network.tf
outputs.tf
postgresql.tf
prod.tfvars
README.md
redis.tf
resource-group.tf
secrets.tf
staging.tfvars
variables.tf
versions.tf
deploy.sh
gcp/
.tflint.hcl
cloud-run.tf
cloud-sql.tf
data-host.tf
dns.tf
examples/
minimal/
main.tf
outputs.tf
terraform.tfvars.example
variables.tf
locals.tf
memorystore.tf
network.tf
outputs.tf
README.md
registry.tf
secrets.tf
services.tf
storage.tf
terraform.tfvars.example
user-data.sh.tftpl
variables.tf
versions.tf
install-server.sh
install.sh
LICENSE
LICENSES/
... 1112 moreFAQ
observal is a Claude Code plugin with 6 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes observal-admin, observal-advanced, observal-agents. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is observal?
- Observal is a local registry and analytics platform for your AI components. Setup Observal, define the scope and share your Skills, MCPs and Agents.
- How do I install observal?
- Run these in Claude Code: npx -y skills add Observal/Observal --agent claude-code. Then prompt normally.
- Does observal auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is observal free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.