Add optional AI developer tools profile for Codex and Claude Code

[codeforester]

Summary

Add an explicit opt-in AI developer tools profile for Base developer setup. The initial scope should cover OpenAI Codex CLI and Anthropic Claude Code as optional developer accelerators, not mandatory --dev prerequisites.

Decision for now: track this as one umbrella issue because the product boundary, command UX, manifest/config shape, check/doctor behavior, and tests should be designed together. Split into separate Codex and Claude Code implementation issues only if the installer or diagnostic paths diverge enough to justify separate work.

Product decision

Do not make Codex or Claude Code part of plain basectl setup --dev.

Plain --dev should remain the set of tools required to develop, test, lint, and release Base itself. AI coding assistants require explicit user/account/policy choices and should be opt-in.

Preferred UX direction:

basectl setup --dev --ai
basectl check --dev --ai
basectl doctor --dev --ai
basectl onboard --dev --ai

A later manifest/config shape could also support named dev profiles, for example:

dev:
  profiles:
    ai:
      tools:
        - codex
        - claude-code

Initial scope

• Add an explicit AI-tools opt-in path, likely --ai, for setup, check, doctor, and onboard.
• Detect codex on PATH and report its resolved path and version when possible.
• Detect claude on PATH and report its resolved path and version when possible.
• Keep missing AI tools as non-errors unless the AI profile was explicitly requested.
• When the AI profile is requested, report missing tools with actionable install guidance.
• Do not manage OpenAI or Anthropic credentials directly.
• Do not silently run login flows.
• Do not install these tools as part of ordinary Base setup.
• Prefer official install/update guidance at implementation time.

Current official install references

• OpenAI Codex CLI getting started: https://help.openai.com/en/articles/11096431
• Anthropic Claude Code setup: https://docs.anthropic.com/en/docs/claude-code/getting-started

Implementation should re-check these references when work starts because both tools are moving quickly.

Design considerations

• Codex and Claude Code are powerful local coding agents. Installing them should require explicit consent.
• Both tools require account/authentication choices that Base should not own.
• Organizations may allow one tool, both tools, or neither.
• Install methods may change quickly; Base should avoid brittle hardcoded assumptions where possible.
• Base should diagnose local state and provide fix guidance without becoming an AI-agent package manager.
• Existing lib/base/dev_manifest.yaml currently models Homebrew-managed developer tools. AI tools may require a separate profile/adaptor path instead of forcing them into the existing Homebrew-only artifact model.

Suggested implementation areas

• CLI option parsing for setup, check, doctor, and onboard.
• Completion updates for Bash/Zsh.
• Developer profile or AI-tools detection module.
• Check/doctor output in text and JSON.
• Tests for missing, installed, and version-command-failure cases.
• Documentation in README and relevant docs pages.

Acceptance criteria

• basectl setup --dev behavior remains unchanged.
• basectl check --dev and basectl doctor --dev behavior remains unchanged unless --ai is passed.
• basectl check --dev --ai reports Codex and Claude Code state without mutating the machine.
• basectl doctor --dev --ai prints stable finding IDs and actionable fix guidance.
• basectl setup --dev --ai --dry-run shows what would be installed without installing anything.
• basectl setup --dev --ai installs or delegates installation only after explicit opt-in.
• Missing auth is reported as guidance, not auto-remediated by Base.
• Text and JSON output are covered by tests.
• Shell completions include --ai where supported.
• Docs explain why AI tools are optional and why Base does not manage credentials.

Split criteria

Create follow-up issues for individual tools if any of these become true:

• Codex and Claude Code need substantially different installer abstractions.
• One tool needs platform-specific handling that would block the other.
• One tool requires a separate auth/status diagnostic model.
• One tool is ready to ship while the other needs further design.

Notes from local environment

At the time this issue was created, the local machine had both commands available:

codex  -> /Applications/Codex.app/Contents/Resources/codex
claude -> /usr/local/bin/claude

claude --version also emitted a Bun CPU/AVX warning before printing the Claude Code version. That is a useful example of the kind of diagnostic detail basectl doctor --dev --ai could surface.