{"id":49181306,"url":"https://github.com/php-workx/fuse","last_synced_at":"2026-04-23T01:31:02.563Z","repository":{"id":344012026,"uuid":"1179660494","full_name":"php-workx/fuse","owner":"php-workx","description":"A local firewall for AI agent commands","archived":false,"fork":false,"pushed_at":"2026-04-21T07:15:14.000Z","size":2002,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T09:27:14.984Z","etag":null,"topics":["ai-safety","claude-code","cli","codex","developer-tools","golang","guardrails","mcp","security"],"latest_commit_sha":null,"homepage":"https://github.com/php-workx/fuse#readme","language":"Go","has_issues":true,"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/php-workx.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":null,"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":null}},"created_at":"2026-03-12T08:51:01.000Z","updated_at":"2026-04-21T07:15:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/php-workx/fuse","commit_stats":null,"previous_names":["php-workx/fuse"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/php-workx/fuse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-workx%2Ffuse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-workx%2Ffuse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-workx%2Ffuse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-workx%2Ffuse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/php-workx","download_url":"https://codeload.github.com/php-workx/fuse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-workx%2Ffuse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32162601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-safety","claude-code","cli","codex","developer-tools","golang","guardrails","mcp","security"],"created_at":"2026-04-23T01:31:01.694Z","updated_at":"2026-04-23T01:31:02.524Z","avatar_url":"https://github.com/php-workx.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fuse\n\nA local firewall for AI agent commands.\n\n[![CI](https://github.com/php-workx/fuse/actions/workflows/ci.yml/badge.svg)](https://github.com/php-workx/fuse/actions/workflows/ci.yml)\n[![Go](https://img.shields.io/github/go-mod/go-version/php-workx/fuse)](https://go.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/hero.gif\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/hero-light.gif\"\u003e\n  \u003cimg alt=\"fuse blocking a dangerous command\" src=\"assets/hero.gif\" width=\"600\"\u003e\n\u003c/picture\u003e\n\n**Status: public beta**\n\n| | Status |\n|---|--------|\n| Platforms | macOS, Linux |\n| Claude Code | primary integration |\n| Codex CLI | beta |\n| Windows | early-adopter testing |\n\n---\n\nAI coding agents run shell commands on your machine. Without a safety layer,\na single bad command can delete your files, data, or cloud resources before\nyou notice.\n\nFuse sits between your AI agent and your shell. It classifies every command\ninto SAFE, CAUTION, APPROVAL, or BLOCKED, then applies your selected profile to\ndecide when risky commands need review. No cloud, no API keys, everything local.\n\n## Install\n\n```bash\n# macOS\nbrew install php-workx/tap/fuse\n\n# Debian/Ubuntu\ncurl -sSfL https://github.com/php-workx/fuse/releases/latest/download/fuse_amd64.deb -o fuse.deb\nsudo dpkg -i fuse.deb\n\n# Fedora/RHEL\ncurl -sSfL https://github.com/php-workx/fuse/releases/latest/download/fuse_amd64.rpm -o fuse.rpm\nsudo rpm -i fuse.rpm\n\n# Alpine\ncurl -sSfL https://github.com/php-workx/fuse/releases/latest/download/fuse_amd64.apk -o fuse.apk\nsudo apk add --allow-untrusted fuse.apk\n\n# Windows PowerShell\nirm https://raw.githubusercontent.com/php-workx/fuse/main/install.ps1 | iex\n\n# From source (requires Go 1.25+)\ngo install github.com/php-workx/fuse/cmd/fuse@latest\n```\n\n## Try it\n\n```bash\n# Enable fuse (ships disabled by default)\nfuse enable\n\n# Block a dangerous command\necho '{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"rm -rf /\"}}' | fuse hook evaluate 2\u003e\u00261\n# =\u003e fuse:POLICY_BLOCK STOP. Recursive force-remove of root, home, or variable path ...\n\n# Safe commands pass silently (exit 0, no output)\necho '{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"ls -la\"}}' | fuse hook evaluate 2\u003e\u00261\n\n# Integrate with your agent\nfuse install claude    # or: fuse install codex\nfuse doctor            # verify the setup (prints hook binary path + build info;\n                       # warns if the binary on PATH is stale)\n```\n\nSee [docs/QUICKSTART.md](docs/QUICKSTART.md) for the full walkthrough, including\nhow to [recognize and fix a stale hook binary](docs/QUICKSTART.md#detecting-a-stale-hook-binary).\n\n## What fuse is\n\n- A classification and gating layer for shell commands and MCP tool calls\n- A local-only tool with zero network dependencies\n- A guardrail that catches obvious mistakes before they execute\n- Configurable via YAML policy with per-tag rule overrides\n- Observable via TUI dashboard (`fuse monitor`), event log, and stats\n\n## What fuse is not\n\n- **Not a sandbox** — hook mode has a TOCTOU window (the agent executes after fuse allows)\n- **Not a replacement for OS-level security** (seccomp, AppArmor, containers)\n- **Not infallible** — classification is heuristic and regex-based\n- **Not a monitoring daemon** — it runs per-invocation, not as a background service\n\nSee [docs/TRUST_MODEL.md](docs/TRUST_MODEL.md) for the full security model, threat\nboundaries, and what fuse touches on your filesystem.\n\n## What fuse touches\n\n| What | Where | Purpose |\n|------|-------|---------|\n| Config | `~/.fuse/config/config.yaml` | User settings |\n| Policy | `~/.fuse/config/policy.yaml` | Custom classification rules |\n| State DB | `~/.fuse/state/fuse.db` | Event log, approvals (SQLite) |\n| HMAC secret | `~/.fuse/state/secret.key` | Approval record signing |\n| Claude hook | `~/.claude/settings.json` | Adds `PreToolUse` hook entries |\n| Codex config | `~/.codex/config.toml`, `~/.codex/hooks.json` | Adds native Bash hook when supported, otherwise fuse-shell MCP server |\n\n**Network:** None. Fuse makes zero network calls. The optional [LLM judge](docs/TRUST_MODEL.md)\ninvokes locally-installed CLI tools which may make their own API calls.\n\n## Uninstall\n\n```bash\n# Remove integrations from Claude Code and Codex\nfuse uninstall\n\n# Also remove all fuse state (~/.fuse/)\nfuse uninstall --purge\n\n# Temporarily disable (zero processing, instant pass-through)\nfuse disable\n\n# Re-enable\nfuse enable\n```\n\n\u003e `fuse uninstall` removes integrations and optionally `~/.fuse/`. It does not\n\u003e remove the binary itself. To fully remove: `fuse uninstall --purge \u0026\u0026 rm $(which fuse)`\n\n## Updating\n\nAgent hooks invoke the `fuse` binary resolved from `PATH`, so to pick up new\nclassification rules or bug fixes you must reinstall the binary — restarting\nyour agent is not enough.\n\n```bash\n# From source\ngo install github.com/php-workx/fuse/cmd/fuse@latest\n\n# Homebrew\nbrew upgrade php-workx/tap/fuse\n\n# Verify the hook will run the new build\nfuse doctor\n```\n\n`fuse doctor` reports the resolved hook binary path and — when the PATH binary\nmatches the running build — its version. For a different (unverified) PATH\nbinary, it reports the SHA-256 hash and file size instead of executing it. It\nwarns with `[ WARN ] fuse binary in PATH` when the PATH binary drifts from the\nbuild you ran `doctor` with. The same warning is emitted by `fuse install\nclaude` and `fuse install codex`. See\n[docs/QUICKSTART.md](docs/QUICKSTART.md#detecting-a-stale-hook-binary) for the\nfull output and fix workflow.\n\n## Why fuse?\n\n**Why not just use Claude Code's built-in approval prompts?**\nClaude Code asks before running some commands, but the rules are opaque and not\nconfigurable. Fuse gives you explicit YAML policy, per-tag overrides, event\nlogging, and a TUI dashboard.\n\n**Why not a shell wrapper or alias?**\nShell wrappers don't intercept MCP tool calls. Fuse works at the hook and MCP\nprotocol level, covering both shell commands and tool invocations.\n\n**Why not a container or VM?**\nContainers are heavy and break agent workflows that need filesystem access. Fuse\nis a lightweight guardrail that runs alongside the agent, not a sandbox.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIntegration details\u003c/strong\u003e\u003c/summary\u003e\n\n### Claude Code\n\n```bash\nfuse install claude           # basic hook (Bash + MCP)\nfuse install claude --secure  # + file tool path checks + recommended Claude settings\n```\n\n### Codex CLI\n\n```bash\nfuse install codex\n```\n\nUses Codex native Bash hooks when supported by the installed Codex CLI, with an\nautomatic fallback to the fuse-shell MCP server on older versions or Windows.\n\n### MCP proxy\n\nConfigure downstream servers in `~/.fuse/config/config.yaml`:\n\n```yaml\nmcp_proxies:\n  - name: aws-mcp\n    command: npx\n    args: [\"-y\", \"@aws/mcp-server\"]\n```\n\n```bash\nfuse proxy mcp --downstream-name aws-mcp\n```\n\n### Manual run mode\n\n```bash\nfuse run --timeout 5m -- \"terraform destroy prod\"\n```\n\n### Observability\n\n```bash\nfuse monitor              # TUI dashboard with live events + approval\nfuse events --limit 20    # recent events\nfuse stats                # decision/agent/workspace breakdown\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDevelopment\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\njust setup       # install tools + configure git hooks\njust dev         # full local quality gate (fmt, vet, lint, test, vuln, semgrep, budgets)\njust pre-commit  # fast checks only\njust test        # tests with race detector + coverage\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n\u003c/details\u003e\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-workx%2Ffuse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphp-workx%2Ffuse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-workx%2Ffuse/lists"}