{"id":51468482,"url":"https://github.com/bulletinmybeard/agent-forge-felix","last_synced_at":"2026-07-06T14:01:23.565Z","repository":{"id":365582752,"uuid":"1260777992","full_name":"bulletinmybeard/agent-forge-felix","owner":"bulletinmybeard","description":"Autonomous diagnose → fix → verify CLI agent for operational problems (Docker, disk, HTTP), built on AgentForge.","archived":false,"fork":false,"pushed_at":"2026-06-18T00:30:33.000Z","size":143,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-18T02:18:19.813Z","etag":null,"topics":["agent-forge","ai-agents","automation","autonomous-agent","cli","devops","diagnostics","incident-response","llm","python","self-healing","troubleshooting"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bulletinmybeard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T21:32:36.000Z","updated_at":"2026-06-18T00:28:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bulletinmybeard/agent-forge-felix","commit_stats":null,"previous_names":["bulletinmybeard/agent-forge-felix"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bulletinmybeard/agent-forge-felix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fagent-forge-felix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fagent-forge-felix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fagent-forge-felix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fagent-forge-felix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bulletinmybeard","download_url":"https://codeload.github.com/bulletinmybeard/agent-forge-felix/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fagent-forge-felix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35193679,"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-07-06T02:00:07.184Z","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":["agent-forge","ai-agents","automation","autonomous-agent","cli","devops","diagnostics","incident-response","llm","python","self-healing","troubleshooting"],"created_at":"2026-07-06T14:01:22.344Z","updated_at":"2026-07-06T14:01:23.551Z","avatar_url":"https://github.com/bulletinmybeard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Felix\n\n[![CI](https://github.com/bulletinmybeard/agent-forge-felix/actions/workflows/ci.yml/badge.svg)](https://github.com/bulletinmybeard/agent-forge-felix/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)\n[![Requires AgentForge](https://img.shields.io/badge/requires-AgentForge-blueviolet)](https://github.com/bulletinmybeard/agent-forge)\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e **Experimental — a personal learning project.**\n\u003e Felix is a sandbox for one question: can an agent take an ambiguous \"X is broken\" prompt and work the whole loop itself, trace the root cause, apply a fix behind a safety gate, and prove it actually worked? Expect rough edges, model-dependent behavior, thin test coverage, and breaking changes.\n\nAutonomous local diagnostic-repair agent. **diagnose. fix. verify.**\n\nInspired by Fix-It Felix (*Wreck-It Ralph*) — \"I can fix it!\", for your systems.\n\n```bash\nfelix \"find out why the docker container xyz-1 is not responding and make it work again\"\nfelix \"my VM is running out of disk space. Free up some safely\"\nfelix \"why does localhost:3000 not respond?\"\nfelix doctor\n```\n\nFelix diagnoses a broken thing, finds the root cause from evidence, proposes a fix, applies it behind a safety gate (with confirmation prompts), verifies the result before/after, and saves a rollback-aware report. It targets **any system-level problem**. Flexibility comes from a retrieved fleet of Agent Skills (see below), not hardcoded domains.\n\n## Architecture\n\nFelix is a thin client over [AgentForge](https://github.com/bulletinmybeard/agent-forge):\n\n- **Brain**: the remote AgentForge web service runs the agent loop, classification, investigation/synthesis, and the safety guard.\n- **Executor**: AgentForge dispatches tool execution to a local SAQ worker (launchd) on the MacBook. That is why Felix can diagnose the local box.\n- **Felix client**: drives a run over the `/ws/chat` WebSocket, renders the live event stream, enforces a risk-tiered confirm policy, runs the mandatory before/after verification, and persists a local run-store + rollback ledger + report under `~/.felix/runs/\u003ctimestamp\u003e/`.\n\n## Modes\n\n| Flag | Effect |\n|:------|:--------|\n| `--dry-run` | Trace the plan via `/api/dry-run`; execute nothing. |\n| `--read-only` | Diagnose and propose only; block every change. |\n| `--apply` | Auto-apply read-only + low-risk fixes. |\n| `--yes` | Auto-confirm medium-risk (high-risk still prompts). |\n| `--deep` | Deeper investigation. |\n\nSafety tiers:\n\n1. read-only (auto)\n2. low (auto with `--apply`)\n3. medium (confirm)\n4. high (blocked by default and needs `--yes` + an explicit confirm).\n\n## Subcommands\n\n```bash\nfelix doctor              # check API, WebSocket, SAQ worker, @felix agent\nfelix last                # show the latest run's report\nfelix explain [RUN_ID]    # root cause + evidence\nfelix undo [RUN_ID]       # revert file changes via revert_file\nfelix replay [RUN_ID]     # replay commands through the dry-run pipeline\n```\n\n## Skill fleet\n\nFelix retrieves the most relevant Agent Skills for each problem and injects them into the run. Skills (open `SKILL.md` format) are acquired from GitHub / [skills.sh](https://www.skills.sh/), indexed into AgentForge's Qdrant vector database via its existing chunker + indexer, and retrieved semantically at runtime.\n\n```bash\nfelix skills pull                       # fetch skills from felix/skills/sources.yaml -\u003e catalog\nfelix skills index                      # chunk + index the catalog into Qdrant\nfelix skills retrieve \"disk is full\"    # preview which skills would be injected\nfelix skills list                       # show the acquired catalog + provenance\n```\n\nThe catalog always includes the bundled system-ops **anchor skills** (`felix/skills/anchors/*.md`) so Felix has core diagnostic know-how regardless of external sources. Add curated GitHub repos via `felix/skills/sources.yaml`.\n\n### Dynamic discovery (skills.sh)\n\nSearch the [skills.sh](https://www.skills.sh/) registry and pull specific skills on demand (same data as `npx skills`, via its JSON API):\n\n```bash\nfelix skills find \"kubernetes crashloop\"          # search the registry\nfelix skills add owner/repo@skill --index        # pull a specific skill + index it\nfelix \"why is pod X crashlooping?\" --discover    # auto-search + pull + index before the run\n```\n\nRetrieval hits the indexer/search service (`search_base`), separate from the chat service (`api_base`). Indexing writes chunk JSON to `skills_chunks_dir`, which must be readable by the indexer host.\n\n## Setup\n\n```bash\npoetry install\ncp config.example.yaml ~/.felix/config.yaml   # edit api_base / api_key\npoetry run felix doctor\n```\n\nRequires a running AgentForge stack that includes the `@felix` agent (baked into the release). See [docs/server-setup.md](docs/server-setup.md). Run `felix doctor` to verify connectivity and local settings.\n\n## Documentation\n\nDocumentation and References live in [`docs/`](docs/):\n\n- [Architecture](docs/architecture.md): the three tiers, run lifecycle, event stream.\n- [CLI reference](docs/cli.md): every command and flag.\n- [Configuration](docs/configuration.md): all config fields, env overrides, `~/.felix` layout.\n- [Safety model](docs/safety.md): risk tiers, confirm policy, read-only gate, egress gating, redaction, skill firewall.\n- [Skill fleet](docs/skills.md): anchors, sources, skills.sh discovery, indexing, retrieval, vetting.\n- [Server setup](docs/server-setup.md): wiring `@felix` into AgentForge.\n- [Runs \u0026 reports](docs/runs-and-reports.md): run-store layout, report format, verdicts, undo/replay.\n\n## License\n\nMIT, see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletinmybeard%2Fagent-forge-felix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbulletinmybeard%2Fagent-forge-felix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletinmybeard%2Fagent-forge-felix/lists"}