{"id":51286567,"url":"https://github.com/focus-mcp/cli","last_synced_at":"2026-06-30T06:03:05.380Z","repository":{"id":351884380,"uuid":"1212900066","full_name":"focus-mcp/cli","owner":"focus-mcp","description":"Focus your AI agents on what matters. 68+ bricks, 1 MCP server, modular context — from 200k to 2k tokens. Works with Claude Code, Cursor, Codex.","archived":false,"fork":false,"pushed_at":"2026-05-24T18:07:20.000Z","size":599,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T19:19:07.972Z","etag":null,"topics":["agent-tools","ai","bricks","claude","claude-code","cli","codex","context-engineering","cursor","focus","ink","llm","marketplace","mcp","model-context-protocol","nodejs","orchestrator","tools","tui","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@focus-mcp/cli","language":"TypeScript","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/focus-mcp.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":null}},"created_at":"2026-04-16T21:00:58.000Z","updated_at":"2026-05-24T18:06:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/focus-mcp/cli","commit_stats":null,"previous_names":["focus-mcp/cli"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/focus-mcp/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/focus-mcp","download_url":"https://codeload.github.com/focus-mcp/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-mcp%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34954283,"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-30T02:00:05.919Z","response_time":92,"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-tools","ai","bricks","claude","claude-code","cli","codex","context-engineering","cursor","focus","ink","llm","marketplace","mcp","model-context-protocol","nodejs","orchestrator","tools","tui","typescript"],"created_at":"2026-06-30T06:03:04.440Z","updated_at":"2026-06-30T06:03:05.337Z","avatar_url":"https://github.com/focus-mcp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2026 FocusMCP contributors\nSPDX-License-Identifier: MIT\n--\u003e\n\n# @focus-mcp/cli\n\n\u003e Focus your AI agents on what matters. **Measured savings: 65.3% on output tokens** across all 69 bricks ([details](https://github.com/focus-mcp/marketplace/blob/main/benchmarks/equivalence-report.md)).\n\n[![npm](https://img.shields.io/npm/v/@focus-mcp/cli)](https://www.npmjs.com/package/@focus-mcp/cli)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![CI](https://github.com/focus-mcp/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/focus-mcp/cli/actions/workflows/ci.yml)\n![Built with Claude Code](https://img.shields.io/badge/built_with-Claude_Code-8A2BE2)\n\n## What\n\nFocusMCP is an MCP (Model Context Protocol) orchestrator. Instead of giving your AI agent ALL your tools at once — polluting its context window — you compose **bricks**: atomic MCP modules that load on demand.\n\n- **68+ official bricks** covering files, code intel, git, shell, reasoning, search, and more\n- **One CLI, one MCP server**, modular capabilities\n- Works with **Claude Code, Cursor, Codex, Gemini CLI**, any MCP-compatible AI\n\n## Install\n\n```bash\nnpm install -g @focus-mcp/cli\n```\n\nOr via the **Claude Code native plugin**:\n\n### Install for Claude Code\n\n**Option 1 — Two lines (works today)**\n```\n/plugin marketplace add focus-mcp/cli\n/plugin install focus-mcp@focus-mcp-cli\n```\n\n**Option 2 — Manual MCP add**\n```bash\nclaude mcp add focus-mcp npx @focus-mcp/cli start\n```\n\n*(Official single-liner `/plugin install focus-mcp@claude-plugins-official` coming once Anthropic accepts the submission.)*\n\nRequires **Node.js ≥ 22**.\n\n## Quick start\n\nAdd FocusMCP as an MCP server in your AI client config:\n\n```json\n{\n    \"mcpServers\": {\n        \"focus\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"@focus-mcp/cli\", \"start\"]\n        }\n    }\n}\n```\n\nFor **Claude Code** specifically, this is already wired via the native plugin above.\n\nThen browse and manage bricks:\n\n```bash\nfocus browse          # Interactive TUI — browse, search, install/uninstall bricks\nfocus search git      # Search the catalog for bricks matching \"git\"\nfocus add echo        # Install the \"echo\" brick\nfocus list            # Show all installed bricks\nfocus info echo       # Show details for a specific brick\n```\n\n## Windows\n\nFocusMCP supports Windows as of `@focus-mcp/cli \u003e= 2.3.1`. Earlier versions may fail when installing or loading bricks because of Windows `.cmd` wrappers and path separator handling.\n\n### Requirements\n\n- Windows 10/11\n- Node.js \u003e= 22\n- npm available from PowerShell or Command Prompt\n- `@focus-mcp/cli \u003e= 2.3.1`\n\n### Install\n\n```powershell\nnpm install -g @focus-mcp/cli@latest\nfocus --version\n```\n\nExpected:\n\n```\n@focus-mcp/cli 2.3.1 or newer\n```\n\n### Test\n\n```powershell\nfocus search cache\nfocus add cache\nfocus list\n```\n\n### MCP client config on Windows\n\nFor Windows MCP clients, prefer launching through `cmd.exe` and the `.cmd` shim, especially when using nvm4w or when the client does not inherit your interactive shell PATH.\n\nGeneric MCP JSON:\n\n```json\n{\n    \"mcpServers\": {\n        \"focus\": {\n            \"command\": \"C:\\\\\\\\Windows\\\\\\\\System32\\\\\\\\cmd.exe\",\n            \"args\": [\"/d\", \"/c\", \"focus.cmd\", \"start\"]\n        }\n    }\n}\n```\n\nIf your MCP client cannot find `focus.cmd`, use the full path:\n\n```json\n{\n    \"mcpServers\": {\n        \"focus\": {\n            \"command\": \"C:\\\\\\\\Windows\\\\\\\\System32\\\\\\\\cmd.exe\",\n            \"args\": [\"/d\", \"/c\", \"C:\\\\\\\\nvm4w\\\\\\\\nodejs\\\\\\\\focus.cmd\", \"start\"],\n            \"env\": {\n                \"PATH\": \"C:\\\\\\\\nvm4w\\\\\\\\nodejs;C:\\\\\\\\Users\\\\\\\\\u003cuser\u003e\\\\\\\\AppData\\\\\\\\Roaming\\\\\\\\npm;C:\\\\\\\\Windows\\\\\\\\System32;C:\\\\\\\\Windows\"\n            }\n        }\n    }\n}\n```\n\n### Codex on Windows\n\nAdd this to `%USERPROFILE%\\.codex\\config.toml`:\n\n```toml\n[mcp_servers.focus]\ncommand = \"C:\\\\\\\\Windows\\\\\\\\System32\\\\\\\\cmd.exe\"\nargs = [\"/d\", \"/c\", \"C:\\\\\\\\nvm4w\\\\\\\\nodejs\\\\\\\\focus.cmd\", \"start\"]\nstartup_timeout_sec = 30\ntool_timeout_sec = 120\n\n[mcp_servers.focus.env]\nPATH = \"C:\\\\\\\\nvm4w\\\\\\\\nodejs;C:\\\\\\\\Users\\\\\\\\\u003cuser\u003e\\\\\\\\AppData\\\\\\\\Roaming\\\\\\\\npm;C:\\\\\\\\Windows\\\\\\\\System32;C:\\\\\\\\Windows\"\nFOCUS_NO_UPDATE_NOTIFY = \"1\"\n```\n\nReplace `\u003cuser\u003e` and the Node path if you do not use nvm4w.\n\n### Troubleshooting\n\nIf brick installation fails with:\n\n```\nspawn npm ENOENT\n```\n\nupdate FocusMCP:\n\n```powershell\nnpm install -g @focus-mcp/cli@latest\n```\n\nIf brick loading fails with:\n\n```\nescapes bricksDir\n```\n\nmake sure `focus --version` reports `2.3.1` or newer.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `focus list` | List installed bricks (reads `~/.focus/center.json`) |\n| `focus info \u003cname\u003e` | Show details for a brick (version, catalog, config) |\n| `focus start` | Launch FocusMCP as an MCP server over stdio |\n| `focus add \u003cname\u003e` | Install a brick from the catalog |\n| `focus remove \u003cname\u003e` | Uninstall a brick |\n| `focus search \u003cquery\u003e` | Search the catalog |\n| `focus catalog` | Show and manage catalog sources |\n| `focus browse` | Interactive TUI browser (see below) |\n\n## Interactive TUI — `focus browse`\n\n`focus browse` opens a full-screen terminal interface to explore, search, and manage bricks without leaving your terminal.\n\n```\n┌─ Bricks (68) ────────────────┬─ echo ───────────────────────────────────┐\n│ \u003e echo              ✓        │                                          │\n│   indexer                    │  A simple echo brick for testing.        │\n│   shell                      │                                          │\n│   git-log                    │  Version   ^1.0.0                        │\n│   web-search                 │  Source    @focus-mcp/echo               │\n│   …                          │  Status    installed                     │\n│                              │                                          │\n│  / search  i install         │  [i] Install   [u] Uninstall             │\n│  ↑↓ nav    Enter open        │  [?] Help                                │\n└──────────────────────────────┴──────────────────────────────────────────┘\n```\n\n**Keybindings:**\n\n| Key | Action |\n|---|---|\n| `↑` / `↓` | Navigate the brick list |\n| `Enter` | Open brick details |\n| `/` | Search / filter |\n| `i` | Install selected brick |\n| `u` | Uninstall selected brick |\n| `?` | Toggle help overlay |\n| `q` / `Esc` | Quit |\n\n## Filtering exposed tools\n\nBy default, `focus start` exposes all tools from every loaded brick plus the focus management\ntools (`focus_*`). You can hide specific tools using a blacklist.\n\n### Per-launch: `--hide`\n\n```bash\n# Hide a single tool\nfocus start --hide=sym_get\n\n# Hide an entire family with a glob\nfocus start --hide=\"focus_*\"\n\n# Hide multiple patterns (comma-separated)\nfocus start --hide=\"sym_get,ts_cleanup\"\n```\n\nPatterns support a trailing `*` glob (`focus_*` matches `focus_install`, `focus_list`, etc.).\nExact names are also accepted.\n\n\u003e **Note:** `focus_tools` is always visible regardless of the hidden list, so you can always\n\u003e manage tool visibility from within your AI client.\n\n### Persistent config: `~/.focus/config.json`\n\nAdd a `tools` section to persist filters across sessions:\n\n```json\n{\n    \"tools\": {\n        \"hidden\": [\"sym_get\", \"fo_delete\"],\n        \"alwaysLoad\": [\"ts_index\"]\n    }\n}\n```\n\nCLI flags override the config file. If neither is set, all tools are exposed (default).\n\nAdd `--pin=\u003cpatterns\u003e` to mark tools as always-loaded (surfaced as `_meta.anthropic/alwaysLoad: true` in MCP responses):\n\n```bash\nfocus start --pin=\"ts_index,sym_find\"\n```\n\n### Manage from the terminal: `focus tools:`\n\n```bash\nfocus tools:list               # show current hidden + alwaysLoad lists\nfocus tools:hide sym_get       # add sym_get to the hidden list\nfocus tools:hide \"focus_*\"     # hide an entire family (glob)\nfocus tools:show sym_get       # remove sym_get from the hidden list\nfocus tools:pin ts_index       # mark ts_index as alwaysLoad\nfocus tools:unpin ts_index     # remove ts_index from alwaysLoad\nfocus tools:clear              # reset both lists\n\n# Legacy aliases (permanent, no deprecation):\nfocus filter list\nfocus filter hide sym_get\n```\n\nChanges are written to `~/.focus/config.json` and take effect on the next `focus start`.\n\n### From your AI client: `focus_tools` MCP tool\n\nThe `focus_tools` MCP tool lets your AI agent manage tool visibility directly:\n\n```\nfocus_tools action=hide   pattern=sym_get\nfocus_tools action=show   pattern=sym_get\nfocus_tools action=pin    pattern=ts_index\nfocus_tools action=unpin  pattern=ts_index\nfocus_tools action=list\nfocus_tools action=clear\n```\n\nRestart `focus start` (or reload your MCP client) to apply changes.\n\n## Architecture\n\n```\nAI client (Claude Code, Cursor, Codex, …)\n       │ stdio (JSON-RPC / MCP)\n       ▼\n@focus-mcp/cli  (this package)\n  ├─ @modelcontextprotocol/sdk  StdioServerTransport\n  ├─ @focus-mcp/core            Registry + EventBus + Router + brick loader\n  └─ ~/.focus/center.json       user brick declarations\n```\n\n**Bricks** are atomic MCP modules. Each brick exposes exactly one domain of tools to the AI agent. You declare which bricks you want in `~/.focus/center.json`; FocusMCP loads them on demand when `focus start` is called.\n\n**Why not give the agent all tools at once?** Because a 200k-token context window filled with hundreds of tool descriptions leaves very little room for actual work. FocusMCP keeps the agent's context lean — ~2k tokens for the orchestrator itself — and loads domain-specific tools only when needed.\n\n## For AI agents\n\nIf you are an AI agent (Claude Code, Cursor, Cline, Codex, etc.) and want to bootstrap on a new project using FocusMCP, read the **[Agent Bootstrap Guide](./docs/AGENT_GUIDE.md)**. It covers stack detection, brick search and install, tool pinning, and common workflows — optimized for LLM consumption.\n\n## Links\n\n- **Marketplace**: \u003chttps://github.com/focus-mcp/marketplace\u003e\n- **Core library**: \u003chttps://github.com/focus-mcp/core\u003e\n- **Official catalog**: \u003chttps://raw.githubusercontent.com/focus-mcp/marketplace/main/publish/catalog.json\u003e\n- **Website**: \u003chttps://focusmcp.dev\u003e\n\n## AI-assisted development\n\nFocusMCP was built with heavy Claude Code assistance — its architecture, implementation,\ndocs, and tests have all been co-authored with AI. We embrace this openly because:\n\n1. **Transparency matters** — we'd rather disclose it than pretend otherwise\n2. **AI tooling is the context** — we're building tools for AI agents, it makes sense to use them\n3. **Quality over origin** — what matters is that the code is tested, reviewed, and working\n\n**Your AI-assisted contributions are welcome.** We don't require you to hide the fact that\nClaude, Copilot, Cursor, or any other tool helped you. What we do expect:\n\n- Tests pass, code is typed, lint is green\n- You've read the diff and understand what the PR does\n- Conventional Commits, clear PR description\n- You can explain your design choices during review\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guidelines.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffocus-mcp%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffocus-mcp%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffocus-mcp%2Fcli/lists"}