claude-cli — sidecar phân tích thị trường— market-analysis sidecar

fxconsole's analysis:run command builds the cards on /analysis in a hybrid way: price levels are computed deterministically from OHLC data in PHP, and Claude writes the narrative. fxconsole posts the prompt to this container, which runs claude -p authenticated with the team's monthly Claude subscription (OAuth), so the analysis feature does not also pay for a metered API key.

It runs on the compose default network only, with no published port. fxconsole (the app and scheduler containers) reaches it at http://claude-cli:8788, taken from the claude_cli_url setting (default from the CLAUDE_CLI_URL variable).

• The image is based on node:22-bookworm-slim, installs @anthropic-ai/claude-code globally (build arg CLAUDE_CODE_VERSION, default latest) plus the Express server in server.js. node-pty needs python3, make and g++ at build time.
• It runs as the node user; /home/node/.claude and /home/node/.config are pre-created so the mounted volumes are owned by node (UID 1000), not root.
• ANALYZE_CONCURRENCY: "1": only one claude -p at a time, to protect the shared quota. Raise it cautiously.
• The claude_creds and claude_config named volumes are declared at the bottom of the compose file; they grant access to the subscription, so back them up and keep them private.

• By default /analyze runs with no tools (--allowed-tools ""): one turn, predictable spend. With web_search=true that single call gets WebSearch,WebFetch through both --tools and --allowed-tools (in -p mode nobody can answer a permission prompt); the call becomes a multi-turn agent loop and costs several times as much.
• effort accepts only low, medium, high, xhigh, max; anything else is dropped rather than failing the call.
• usage carries input/output/cache tokens, cost_usd, turns and web-search count, read defensively from the CLI's JSON envelope. fxconsole adds it up in Redis to enforce its own budget.
• Re-login must keep one claude login process alive (under a PTY) across the two calls, because OAuth-PKCE holds the code_verifier in process memory. A session lives at most 10 minutes; a new /relogin/start cancels any half-finished one.

Credentials live under the node user's home, mounted on the claude_creds / claude_config named volumes so they survive docker compose up --build. Run on the Docker host, in monitor/fxconsole:

You do not edit .env. Either:

• From the UI: /admin/analysis shows a red "CLI cần đăng nhập lại" banner → click Re-login → a URL appears → open it, copy the code → paste and Save.
• From a shell: docker compose exec -it claude-cli claude login.

Day to day the CLI auto-refreshes the short-lived access token; you only touch this occasionally. Note that authed only checks that a credentials file exists and cannot read the refresh-token expiry; the real signal is runs starting to fail with auth errors.

The OAuth credentials are just files on the volume. Back them up after a successful login so a lost volume doesn't force a re-auth:

• ClaudeService has two engines: cli (default and active: this sidecar) and api (the metered Messages API, dormant, used only if an admin sets analysis_engine=api and a key exists). The cli engine never falls back to the API.
• The CLI cannot enforce a JSON schema, so analyzeViaCli() demands a single JSON object (bias, summary_md, scenario_up, scenario_down, next_event, confidence), extracts the first balanced object, and retries up to 3 times with a stricter nudge. Long reports use analyzeTextViaCli() (plain text, up to 2 attempts).
• Every attempt that reached the model is recorded in the budget (AnalysisBudget), even a malformed reply. A timeout after error is not retried (a retry gets the same clock and only burns more quota).
• Timeouts: a normal call gets 90 s; a web-search call uses analysis_web_timeout_ms (default 280 000 ms, max 900 000 ms). The HTTP client always waits 20 s longer than the timeout it sends. The sidecar clamps the value to its own ANALYZE_TIMEOUT_MS (compose sets 900 000).
• The admin page calls /health and /models (8 s timeout), /relogin/start (35 s) and /relogin/complete (60 s) through the routes /admin/analysis/health, /admin/analysis/relogin/start and /admin/analysis/relogin/complete.

The scheduler ticks analysis:run --scope=global every minute but runs it once per "slot"; the command aborts cleanly when no pairs are enabled or the sidecar isn't authed. Custom prompts have their own weekly schedule (--scope=weekly). Both share the analysis-run mutex so they never fight over a concurrency-1 sidecar. The CLI can't report the subscription's real remaining quota, so fxconsole meters its own spend. Settings (env values are defaults; admins override them live on /admin/analysis / /admin/settings):

The image installs @anthropic-ai/claude-code@latest by default. Pin it so an upstream release can't change the login flow or flags under the /relogin wrapper:

After a bump, verify inside the container that:

• claude -p --output-format json --allowed-tools "" --model <id> prints a JSON envelope with a result field.
• claude login prints an OAuth URL, then waits on stdin for a pasted code.

If the login sub-command or its wording changed, adjust via env in docker-compose.yml: LOGIN_CMD, LOGIN_URL_RE, LOGIN_OK_RE.

Related: fxconsole (web) · Deployment guide.