@devries-cameron20 / composio-1 / commits / 98b7fcee2
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(cli): agent-aware plugin acquisition hint (PRDE-1153) (#3981)

## Summary [PRDE-1153](https://linear.app/composio/issue/PRDE-1153) adds a small acquisition hint when the bare CLI is running inside Claude Code or Codex and the Composio plugin is not installed in that host: ```text Tip: running under Claude Code without the Composio plugin — 'composio setup' installs it. ``` The hint is written only to stderr, including in non-TTY shells, because agent tool calls commonly capture stderr. It never changes stdout or command results. ## When the hint appears All of the following must be true: - The CLI detects Claude Code via `CLAUDECODE`, or Codex via `CODEX_THREAD_ID` / `CODEX_SANDBOX`. - The host's plugin state confidently shows that `composio@composio` is absent. - A hint has not been shown for that host within the last 24 hours. - The current command is not `composio setup`, including when root flags precede the command. - The invocation is not a child of `composio run`. Unreadable or unrecognized plugin state suppresses the hint rather than risking a false positive. ## Host state and throttling - Claude Code presence is read from `~/.claude/plugins/installed_plugins.json`. - Codex presence is read from `~/.codex/config.toml`. - `CLAUDE_CONFIG_DIR` and `CODEX_HOME` overrides are honored; blank overrides fall back to the standard paths. - Per-host throttle stamps live under `<COMPOSIO_CACHE_DIR or ~/.composio>/plugin-hints/`. The throttle is best-effort rather than a correctness boundary. Two processes racing exactly as a stale stamp is replaced may both print the same tip; the only consequence is a duplicate advisory line. ## Implementation notes - Detection and presence checks use local environment variables and small local files only—there is no network request or background worker. - Shared agent-host names, labels, and the plugin ID are centralized in `agent-host.ts` and reused by the existing setup flow. - This PR covers plugin acquisition only. Plugin freshness and CLI update messaging remain separate concerns. ## Verification - `plugin-hint.test.ts`: 15 passing tests covering host detection, plugin presence, suppression rules, per-host throttling, custom/blank host paths, root flags, concurrency, and non-TTY stderr. - CLI source typecheck: passed. - CLI test typecheck: passed. - Changed-file oxlint and `git diff --check`: passed.

Kshitij Jhunjhunwala committed Jul 30, 2026 at 15:58 UTC 98b7fcee272a0ca390eff7467352109f59578a3a

No changes.