{"id":49553989,"url":"https://github.com/ogiboy/agentic-trader","last_synced_at":"2026-06-05T23:01:08.129Z","repository":{"id":349026727,"uuid":"1196758553","full_name":"ogiboy/agentic-trader","owner":"ogiboy","description":"Agentic Trader is a strict, local-first, multi-agent paper trading system for Ollama-class models.","archived":false,"fork":false,"pushed_at":"2026-06-04T00:08:48.000Z","size":16319,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T00:15:05.462Z","etag":null,"topics":["agent-orchestration","agent-trading","agentic-trader","ai-trade","llm","ollama","tradebot","trader"],"latest_commit_sha":null,"homepage":"https://ogiboy.github.io/agentic-trader/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ogiboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T02:31:37.000Z","updated_at":"2026-06-03T19:32:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"14836da3-b9f5-4d39-9f3b-cfe1bd951d43","html_url":"https://github.com/ogiboy/agentic-trader","commit_stats":null,"previous_names":["ogiboy/agentic-trader"],"tags_count":363,"template":false,"template_full_name":null,"purl":"pkg:github/ogiboy/agentic-trader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogiboy%2Fagentic-trader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogiboy%2Fagentic-trader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogiboy%2Fagentic-trader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogiboy%2Fagentic-trader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ogiboy","download_url":"https://codeload.github.com/ogiboy/agentic-trader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogiboy%2Fagentic-trader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33962959,"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-05T02:00:06.157Z","response_time":120,"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-orchestration","agent-trading","agentic-trader","ai-trade","llm","ollama","tradebot","trader"],"created_at":"2026-05-03T01:11:11.995Z","updated_at":"2026-06-05T23:01:08.070Z","avatar_url":"https://github.com/ogiboy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentic Trader\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ogiboy_agentic-trader\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ogiboy_agentic-trader)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=ogiboy_agentic-trader\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=ogiboy_agentic-trader)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ogiboy_agentic-trader\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=ogiboy_agentic-trader)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=ogiboy_agentic-trader\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ogiboy_agentic-trader)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=ogiboy_agentic-trader\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=ogiboy_agentic-trader)\n[![Python](https://img.shields.io/badge/python-3.13-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![pnpm](https://img.shields.io/badge/pnpm-11.0.9-F69220?logo=pnpm\u0026logoColor=white)](https://pnpm.io/)\n[![CI](https://github.com/ogiboy/agentic-trader/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ogiboy/agentic-trader/actions/workflows/ci.yml)\n[![SonarCloud CI](https://github.com/ogiboy/agentic-trader/actions/workflows/sonar.yml/badge.svg?branch=main)](https://github.com/ogiboy/agentic-trader/actions/workflows/sonar.yml)\n[![Version Check](https://github.com/ogiboy/agentic-trader/actions/workflows/version-check.yml/badge.svg?branch=main)](https://github.com/ogiboy/agentic-trader/actions/workflows/version-check.yml)\n[![Release](https://github.com/ogiboy/agentic-trader/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/ogiboy/agentic-trader/actions/workflows/release.yml)\n[![Binaries](https://github.com/ogiboy/agentic-trader/actions/workflows/binaries.yml/badge.svg?branch=main)](https://github.com/ogiboy/agentic-trader/actions/workflows/binaries.yml)\n[![Docs](https://github.com/ogiboy/agentic-trader/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/ogiboy/agentic-trader/actions/workflows/docs.yml)\n[![Latest Release](https://img.shields.io/github/v/release/ogiboy/agentic-trader?sort=semver\u0026display_name=tag)](https://github.com/ogiboy/agentic-trader/releases)\n[![License: LGPL-3.0-or-later](https://img.shields.io/badge/license-LGPL--3.0--or--later-blue.svg)](LICENSE)\n\n```ascii\n █████╗ ██████╗ ███████╗███╗ ██╗████████╗██╗ ██████╗\n██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝██║██╔════╝\n███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║ ██║██║\n██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ██║██║\n██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║ ██║╚██████╗\n╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═════╝\n\n████████╗██████╗ █████╗ ██████╗ ███████╗██████╗\n╚══██╔══╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗\n ██║ ██████╔╝███████║██║ ██║█████╗ ██████╔╝\n ██║ ██╔══██╗██╔══██║██║ ██║██╔══╝ ██╔══██╗\n ██║ ██║ ██║██║ ██║██████╔╝███████╗██║ ██║\n ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚══════╝╚═╝ ╚═╝\n```\n\nAgentic Trader is a strict, local-first, multi-agent trading system for Ollama-class models, paper-first by default and V1-focused on an approved US-equities buy/sell path. It keeps the Python runtime as the source of truth, uses deterministic guardrails before any broker intent, and records decision context so operator-facing surfaces can be inspected instead of trusted blindly.\n\n## Navigation\n\n| Section | Link |\n| -------------------- | ---------------------------------------- |\n| Overview | [What it is](#overview) |\n| Features | [Core capabilities](#features) |\n| Installation | [Install paths](#installation) |\n| Quick Start | [First commands](#quick-start) |\n| Binaries / Releases | [Release builds](#releases--binaries) |\n| Web UI | [Local command center](#web-gui) |\n| Documentation | [Docs site](#documentation) |\n| Development | [Contributor workflow](#development) |\n| Uninstall / Cleanup | [Local cleanup](#uninstall--cleanup) |\n| License / Disclaimer | [Terms and safety](#license--disclaimer) |\n\n## Overview\n\nAgentic Trader is not a generic chat bot or hidden brokerage switch. The runtime uses a staged specialist graph, structured model outputs, a deterministic execution guard, DuckDB-backed persistence, and broker accounting. The default posture is local-first, paper-first, and explicit about missing data, model readiness, and blocked execution paths; V1 still targets an active US-equities buy/sell path through approved paper and Alpaca readiness gates.\n\nThe repository is now a small monorepo-style workspace:\n\n| Path | Purpose |\n| ----------------- | ------------------------------------------------------------------------------ |\n| `agentic_trader/` | Python core runtime, CLI, agents, storage, workflows, and broker contracts |\n| `main.py` | Root launcher for the Python CLI layer |\n| `webgui/` | Local Next.js Web GUI that shells out to existing Python CLI/runtime contracts |\n| `docs/` | Separate Next.js documentation site intended for GitHub Pages |\n| `tui/` | Ink terminal control room managed through the root pnpm workspace |\n\n## Features\n\n- Python CLI entrypoint: `agentic-trader = \"agentic_trader.cli:app\"`\n- Strict paper-trading runtime with model/provider readiness checks\n- Specialist agent pipeline with manager synthesis and execution guardrails\n- DuckDB-backed run records, traces, trade context, journal, and portfolio state\n- Optional research sidecar feed for source health, world-state snapshots, and future CrewAI-backed deep dives without replacing the core runtime\n- Ink TUI, Rich/admin menu, live monitor, and JSON status surfaces\n- Local Web GUI that delegates to the Python runtime instead of replacing it\n- Static-exportable docs site for setup, architecture, QA, and development notes\n- Root pnpm workspace and thin Makefile aliases for setup, checks, builds, and local app startup\n- Release automation for semantic versioning, changelog updates, GitHub Releases, and packaged CLI binaries\n\n## Installation\n\n### Optional System Bootstrap\n\nFor a fresh machine, start with the interactive system-tool check. It detects\nthe tools around the app without silently installing paid/browser helpers:\n\n```bash\nmake bootstrap-dry-run\nmake bootstrap\n```\n\nFor the full first-run product path, use the launcher alias. It runs the\ninteractive bootstrap, project setup, and then opens `main.py`:\n\n```bash\nmake launch\n# or preview without mutating local state\nmake launch-dry-run\n```\n\n`bootstrap` can offer macOS installs for `uv`, Node, `pnpm`, Ollama, Firecrawl,\nand the optional Camofox/RuFlo tooling when requested. It also offers a\n`~/.local/bin/agentic-trader` symlink after the uv environment has created the\nconsole entrypoint and warns when PATH resolves to a stale entrypoint from\nanother checkout. Firecrawl still requires user-owned authentication through\n`firecrawl login --browser` or `FIRECRAWL_API_KEY` in an ignored env file.\nRuntime auto-start flags only supervise already-installed local helpers; they\ndo not install tools, pull models, create accounts, or mutate trading policy.\nWhen an Ollama, Firecrawl, or Camofox ownership decision is already persisted,\nbootstrap reports that decision instead of asking again; change it explicitly\nwith `agentic-trader tool-ownership set ...` before rerunning bootstrap. The\nfinal bootstrap summary separates completed, deferred, and failed items and\nprints a `next:` action for deferred setup so the next command is visible.\nFor Camofox, `make setup-camofox` installs helper dependencies without running\nbrowser-download scripts; `make fetch-camofox` downloads the optional Camoufox\nbrowser binary only when you approve that step. The Camofox helper uses the\n`camoufox-js` npm package as its Node.js Camoufox bridge/fetch CLI, so seeing\nthat package during helper setup is expected.\n\n### Python / uv From Source\n\n```bash\nuv python install 3.13\npnpm run install:python\n```\n\nDaily source development and GitHub Actions now default to uv-managed Python\n3.13 from the root `.python-version`. The root package metadata still declares\n`\u003e=3.12,\u003c3.15`, but 3.12 compatibility is no longer the primary CI lane unless\na separate compatibility matrix is added. `scripts/install-python.sh` runs\n`uv sync --locked --python 3.13 --all-extras --group dev`.\n\nWhen changing Python dependencies, use uv as the source of truth:\n`uv add \u003cpackage\u003e` for new packages, `uv lock --upgrade` for upgrades, and\n`uv sync --locked --all-extras --group dev` to restore the full developer\nenvironment. A plain `uv sync` can remove dev-only tools from `.venv`, so use\nthe locked dev sync above for normal source work.\n\nCopy `.env.example` to a local ignored env file only when you need provider/model overrides. Do not put secrets in tracked files.\n\n### Node Workspace\n\n`pnpm` manages the Web GUI, docs site, and Ink TUI from the repository root:\n\n```bash\npnpm install\npnpm approve-builds --all\n```\n\nFor one-command workspace setup, use:\n\n```bash\npnpm run setup\n# or\nmake setup\n```\n\n`setup` installs the root pnpm workspace and verifies that `webgui/`, `docs/`,\nand `tui/` each have their workspace `node_modules` links before syncing the\nroot uv Python environment. If you only need the JavaScript side, run\n`pnpm run setup:node` or `make setup-node`.\n\nOptional helper tools under `tools/` are not root workspace packages by\ndefault. Camofox is installed through explicit tool-root commands such as\n`make setup-camofox` or `pnpm --dir tools/camofox-browser install\n--ignore-workspace --ignore-scripts`, so a normal `pnpm install` does not fetch\nbrowser-helper dependencies or blur app-package ownership.\n\nFor a read-only lifecycle check that does not install dependencies, start\nservices, pull models, open a browser, or start trading, run:\n\n```bash\npnpm run app:doctor\n# or\nmake app-doctor\n```\n\nFor the guided first-run path, preview the composed setup/start flow first:\n\n```bash\npnpm run app:up -- --dry-run\n# or\nmake app-up ARGS=\"--dry-run\"\n```\n\nThe safe `--all` lane runs core setup repair, CrewAI Flow sidecar setup, Web\nGUI service start, and a final `app:doctor` report only after `--yes`:\n\n```bash\npnpm run app:up -- --all --yes\n# or\nmake app-up ARGS=\"--all --yes\"\n```\n\n`app:up` is an orchestrator over the existing lifecycle commands, not a second\nruntime. Optional Camofox dependency install, browser-binary fetch,\nmodel-service start, and Camofox-service start require explicit scopes and\nmatching ownership flags such as `--ollama-owner=app-owned` or\n`--camofox-owner=app-owned`. Host-owned, API/key-only, and skipped choices are\npersisted in `runtime/setup/tool-ownership.json`, surface through\n`setup-status`, Web GUI, and TUI readiness, and remain degraded readiness rather\nthan hidden installs. `setup-status` treats optional CrewAI CLI failures as\nbounded setup notes instead of exposing full global-tool tracebacks as version\nstrings.\n\nInspect or adjust those optional-helper choices directly with:\n\n```bash\nagentic-trader tool-ownership status --json\nagentic-trader tool-ownership set --ollama-owner host-owned --firecrawl-owner api-key-only --camofox-owner skipped --json\n```\n\nThe default V1 model path is internal-first: app-owned Ollama serving `qwen3:8b`\nthrough the repo service status/log surfaces. Host-managed fallback remains\navailable only when the operator records host ownership, and it is never started\nor stopped by app lifecycle commands. Operators who do not want Ollama can keep\nOllama `skipped` and select an OpenAI-compatible adapter explicitly:\n\n```bash\nAGENTIC_TRADER_LLM_PROVIDER=openai-compatible\nAGENTIC_TRADER_BASE_URL=http://127.0.0.1:8080/v1\nAGENTIC_TRADER_MODEL_NAME=your-model\n# optional for authenticated endpoints:\nAGENTIC_TRADER_OPENAI_COMPATIBLE_API_KEY=...\n```\n\nFor the first conservative setup lifecycle facade, start with the plan view:\n\n```bash\npnpm run app:setup -- --dry-run\n# or\nmake app-setup ARGS=\"--dry-run\"\n```\n\nThe only mutating `app:setup` path currently implemented is explicit core\nrepair:\n\n```bash\npnpm run app:setup -- --core --yes\n# or\nmake app-setup ARGS=\"--core --yes\"\n```\n\nThat path runs the existing root Node workspace setup and root uv Python sync\nonly. It does not start a trading daemon, start app-owned services, pull Ollama\nmodels, fetch browser binaries, open the Web GUI, change provider accounts, or\ntouch brokerage configuration. Sidecar, Camofox, model-service, Web GUI launch,\nupdate, and uninstall lanes remain separate opt-in lifecycle slices.\n\nFor app-owned services, preview first and then start or stop only the selected\nservice surfaces:\n\n```bash\npnpm run app:start -- --dry-run\npnpm run app:start -- --webgui --yes\npnpm run app:stop -- --all --yes\n```\n\n`app:start` and `app:stop` do not install dependencies, fetch browsers, pull\nmodels, open the Web GUI browser by default, or start the trading daemon. They\ndelegate ownership checks to `model-service`, `camofox-service`, and\n`webgui-service`, and model/Camofox starts now require persisted app-owned\nownership before they run. Host-owned tools are not claimed or stopped. If an\napp-owned Web GUI process cannot be stopped, its state is preserved for retry\ninstead of being reclassified as an external listener.\n\nFor the explicit update lane, preview first and then choose native dependency\nowners:\n\n```bash\npnpm run app:update -- --dry-run\npnpm run app:update -- --core --sidecar --build --status --yes\n```\n\n`app:update` can update root pnpm, root uv, CrewAI Flow sidecar uv, and optional\nCamofox helper package dependencies, then run checks and `app:doctor`. It does\nnot fetch browser binaries, pull Ollama models, start or stop services, delete\nruntime state, touch secrets or brokerage config, or start the trading daemon.\n\nFor conservative local uninstall, preview first and select only app-owned\ngenerated scopes:\n\n```bash\npnpm run app:uninstall -- --dry-run\npnpm run app:uninstall -- --artifacts --deps --yes\n```\n\n`app:uninstall` can remove generated build/test caches, local dependency\ndirectories, the repo-local pnpm store, and app-owned helper service logs/state.\nRecorded service state files block `--service-state` removal until the matching\n`app:stop` command has cleared the app-owned process record. It preserves\nignored env files, secrets, provider accounts, brokerage configuration,\nhost-owned services, global tools, and trading runtime evidence such as DuckDB.\n\n### Optional Web GUI\n\n```bash\npnpm dev:webgui\nagentic-trader webgui-service start\n```\n\nThe Web GUI runs on loopback, normally\n[http://localhost:3210](http://localhost:3210). The `webgui-service` commands\nrecord app-owned state and log tails under `runtime/webgui_service/`; `stop`\nonly targets the recorded app-owned process.\nIf `AGENTIC_TRADER_WEBGUI_TOKEN` is set for a token-protected or proxied local\nsetup, the browser shell prompts for that token and exchanges it for a\nsame-origin HttpOnly session cookie before dashboard, chat, or runtime API calls\nare allowed. Do not expose the Web GUI without either the app-owned loopback\nlauncher marker or an explicit token.\n\n### Optional Docs Site\n\n```bash\npnpm dev:docs\n```\n\n### Optional Ink TUI\n\n```bash\npnpm start:tui\n```\n\n### Optional CrewAI Research Flow Sidecar\n\nCrewAI is tracked as an isolated uv-managed Flow sidecar under\n`sidecars/research_flow/`. It is not a root dependency and the core runtime does\nnot import it. When the research backend is set to `crewai`, the root process\ncalls the Flow sidecar through a subprocess JSON contract after the sidecar\nenvironment has been installed.\n\n```bash\npnpm run setup:research-flow\npnpm run check:research-flow\n```\n\n`pnpm run run:research-flow` is intentionally gated. It exits with a clear\nmessage unless `OPENAI_API_KEY` is present in the shell, present in the sidecar's\nignored `.env`, or the local no-op flag is set for scaffold validation.\n\n### Optional SEC EDGAR Research And Fundamentals Source\n\nThe research sidecar and the canonical fundamental provider can read official\nSEC JSON APIs, but SEC access is off by default. Enable it only from an ignored\nlocal env file and include an identifying SEC User-Agent/contact string:\n\n```bash\nAGENTIC_TRADER_RESEARCH_MODE=training\nAGENTIC_TRADER_RESEARCH_SIDECAR_ENABLED=true\nAGENTIC_TRADER_RESEARCH_SYMBOLS=AAPL,MSFT\nAGENTIC_TRADER_RESEARCH_SEC_EDGAR_ENABLED=true\nAGENTIC_TRADER_RESEARCH_SEC_EDGAR_USER_AGENT=\"Agentic Trader local contact@example.com\"\n```\n\nThe sidecar normalizes recent filing metadata plus compact official\ncompany-facts metrics into source-attributed research evidence. The runtime\ncanonical provider can also turn SEC companyfacts into structured V1\nfundamental fields for US issuers. Neither path downloads full filing text, and\nneither path writes directly into trading memory.\n\n### Optional Firecrawl And Camofox Research Helpers\n\nFirecrawl and Camofox are optional research fetcher/development helpers behind\n`researchd`. They are disabled by default and only produce normalized\nsource-attributed evidence or provider-health records. Firecrawl uses the\ninternal Python SDK/API-key path first when `FIRECRAWL_API_KEY` is present.\nThe host CLI fallback is used only after the operator records Firecrawl as\n`host-owned`; app-owned/API-only/skipped modes keep that fallback disabled and\nvisible. Raw web text is not passed into trading prompts.\n\n```bash\nAGENTIC_TRADER_RESEARCH_MODE=training\nAGENTIC_TRADER_RESEARCH_SIDECAR_ENABLED=true\nAGENTIC_TRADER_RESEARCH_SYMBOLS=AAPL\nAGENTIC_TRADER_RESEARCH_FIRECRAWL_ENABLED=true\nAGENTIC_TRADER_RESEARCH_FIRECRAWL_CLI=firecrawl\nAGENTIC_TRADER_RESEARCH_CAMOFOX_ENABLED=true\nAGENTIC_TRADER_RESEARCH_CAMOFOX_BASE_URL=http://127.0.0.1:9377\n```\n\nStart the bundled Camofox helper only through the loopback/auth wrapper:\n\n```bash\nCAMOFOX_ACCESS_KEY=$(openssl rand -hex 24) make start-camofox\n```\n\nThe helper starts the HTTP service first and launches the browser on demand by\ndefault. Set `CAMOFOX_BROWSER_PREWARM=true` only when you explicitly want a\nwarm browser and have confirmed the local Camoufox binary is stable.\n\nKeep real provider keys in ignored local env files. The app-managed helper\nprefers `CAMOFOX_ACCESS_KEY`; when only `CAMOFOX_API_KEY` is configured it is\nmirrored into the loopback helper as the global access token so browser routes\nare not left open during local research. These adapters cannot submit orders,\nchange runtime mode, or mutate broker policy.\n\nWhen `AGENTIC_TRADER_RUNTIME_AUTO_START_MODEL_SERVICE=true` and\n`AGENTIC_TRADER_LLM_PROVIDER=ollama`, strict runtime actions can start an\napp-owned loopback Ollama process before checking model generation. Alternate\nmodel adapters are explicit endpoint choices and do not cause the Ollama service\nto be claimed. When `AGENTIC_TRADER_RUNTIME_AUTO_START_CAMOFOX=true` and the\nCamofox research provider is enabled, research refreshes can start an app-owned\nloopback Camofox helper before collecting browser-health evidence. Camofox\nstatus treats a reachable HTTP server with `browserRunning=false` as ready for\non-demand launch by default, while recent browser launch failures in app-owned\nlogs still degrade readiness instead of treating a crash-looping helper as\nusable. Inspect or control these helpers directly with:\n\n```bash\nagentic-trader model-service status --probe-generation --json\nagentic-trader model-service stop --json\nagentic-trader camofox-service status --json\nagentic-trader camofox-service start\nagentic-trader camofox-service stop\n```\n\n### Optional Release Binary\n\nDownload packaged CLI binaries from [GitHub Releases](https://github.com/ogiboy/agentic-trader/releases) when available. Binaries package the Python CLI layer; they do not bundle Ollama, the Web GUI, or the docs app.\n\n## Quick Start\n\n| Command | Purpose |\n| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `python main.py doctor` | Check local runtime, model, database, and configuration readiness |\n| `agentic-trader doctor --json` | Emit the same health check as machine-readable JSON |\n| `python main.py run --symbol AAPL --interval 1d --lookback 180d` | Run one strict paper-trading cycle |\n| `agentic-trader` | Open the operator launcher for Web GUI, daemon, Ink, Rich, setup, and model-service choices |\n| `agentic-trader tui` | Open the primary Ink terminal control room directly |\n| `agentic-trader menu` | Open the Rich/admin fallback menu |\n| `agentic-trader dashboard-snapshot` | Print the shared dashboard payload used by UI surfaces; add `--provider-check` for product-readiness evidence |\n| `agentic-trader setup-status --json` | Inspect source, side-application, and optional-tool readiness |\n| `agentic-trader tool-ownership status --json` | Inspect persisted Ollama/Firecrawl/Camofox ownership choices |\n| `pnpm --silent run app:doctor -- --json` | Read setup, provider, V1, and app-owned service readiness without mutating local state |\n| `pnpm --silent run app:up -- --json --dry-run` | Preview the guided first-run setup/start path and ownership decisions |\n| `pnpm --silent run app:up -- --json --all --yes` | Run the safe first-run lane: core repair, sidecar setup, Web GUI start, final doctor |\n| `pnpm --silent run app:setup -- --json --dry-run` | Preview setup lifecycle steps without installing, starting services, pulling models, or fetching browsers |\n| `pnpm --silent run app:setup -- --json --core --yes` | Run only explicit core repair: root Node workspace setup plus root uv Python sync |\n| `pnpm --silent run app:start -- --json --webgui --yes` | Start only the selected app-owned service surfaces; Web GUI browser open stays opt-in |\n| `pnpm --silent run app:stop -- --json --all --yes` | Stop only app-owned service PIDs recorded by the app |\n| `pnpm --silent run app:update -- --json --dry-run` | Preview the scoped update lane across native dependency owners |\n| `pnpm --silent run app:uninstall -- --json --dry-run` | Preview app-owned artifact/dependency/service-state removal |\n| `make launch` | Run interactive bootstrap, setup, and the primary `main.py` launcher |\n| `agentic-trader model-service status --probe-generation --json` | Inspect configured/app-managed Ollama readiness, generation, and log tails |\n| `agentic-trader model-service start` | Start only an app-owned loopback Ollama process |\n| `agentic-trader model-service pull qwen3:8b` | Pull an Ollama model through the configured/app-owned service |\n| `agentic-trader webgui-service status --json` | Inspect app-owned Web GUI readiness and log tails |\n| `agentic-trader webgui-service start` | Start/open the loopback Web GUI command center |\n\n`--provider-check` readiness performs a tiny generation probe, not just a\nreachability/model-list check. If Ollama can list a model but cannot load it,\nstrict operation gates fail closed before an agent cycle starts.\n\nAdvanced usage belongs in the docs site, not in this landing README.\n\n## Releases / Binaries\n\nStable releases are driven by conventional commits on `main` through `python-semantic-release`. A release bump updates `pyproject.toml`, syncs root/workspace `package.json` versions, prepends `CHANGELOG.md`, creates a strict SemVer `v*` tag such as `v0.9.5`, and opens a GitHub Release.\n\nPreview builds keep SemVer compatibility by using prerelease and build metadata instead of a fourth core version segment. Integration branches such as `V1` produce `next` prereleases like `v0.9.6-next.9870+gabc1234`; feature branches produce `beta` prereleases like `v0.9.6-beta.9870+gabc1234`.\n\nTagged stable builds attach PyInstaller CLI binaries for macOS and Windows to the matching release. Branch pushes also upload the same binaries as workflow artifacts and publish prerelease GitHub Releases for branch testing. Source install remains the most complete developer path; release binaries are for quick CLI/admin use.\n\n## Usage\n\n| Command | Notes |\n| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `agentic-trader doctor` | Human-readable environment check |\n| `agentic-trader operator-workflow` | Show the canonical V1 review order |\n| `agentic-trader hardware-profile --json` | Inspect local hardware/runtime sizing hints |\n| `agentic-trader run --symbol AAPL --interval 1d --lookback 180d` | One paper cycle with strict gates |\n| `agentic-trader launch --symbols AAPL,MSFT --interval 1d --lookback 180d --continuous` | Continuous paper runtime |\n| `agentic-trader monitor --refresh-seconds 1` | Attach to runtime status |\n| `agentic-trader supervisor-status --json` | Inspect daemon state and log tails |\n| `agentic-trader broker-status --json` | Inspect paper/live/simulated backend truth |\n| `agentic-trader finance-ops --json` | Inspect broker/account/PnL/exposure evidence as a read-only trading-desk check |\n| `agentic-trader position-plan-repair --json` / `--apply --json` | Dry-run or apply a broker-free backfill for missing exit plans from executed proposals |\n| `agentic-trader setup-status --json` | Inspect root/sidecar/tool readiness without installing anything |\n| `agentic-trader tool-ownership status --json` | Inspect persisted optional helper ownership choices |\n| `pnpm --silent run app:doctor -- --json` | Inspect setup, service, provider, and V1 readiness without installing or starting anything |\n| `pnpm --silent run app:up -- --json --dry-run` | Preview guided first-run setup/start orchestration and ownership decisions |\n| `pnpm --silent run app:up -- --json --all --yes` | Run the safe first-run lane without hidden model pulls, browser fetches, or daemon start |\n| `pnpm --silent run app:setup -- --json --dry-run` | Preview setup lifecycle steps and deferred optional tool/service actions |\n| `pnpm --silent run app:setup -- --json --core --yes` | Repair only core root dependencies after explicit approval |\n| `pnpm --silent run app:start -- --json --webgui --yes` | Start selected app-owned helper services without installing, pulling models, or launching a trading daemon |\n| `pnpm --silent run app:stop -- --json --all --yes` | Stop only app-owned helper services recorded by the app |\n| `pnpm --silent run app:update -- --json --dry-run` | Preview root/sidecar/tool-root update, build, and status lanes |\n| `pnpm --silent run app:uninstall -- --json --dry-run` | Preview app-owned generated artifact and dependency removal |\n| `agentic-trader model-service status --probe-generation --json` | Inspect local Ollama/service/model/generation readiness |\n| `agentic-trader webgui-service status --json` | Inspect loopback Web GUI service readiness |\n| `agentic-trader provider-diagnostics --json` | Inspect model, source, key, and fallback readiness |\n| `agentic-trader v1-readiness --json` | Inspect V1 paper-operation and Alpaca paper-readiness checks; add `--provider-check` before longer paper runs and to verify local-model generation |\n| `agentic-trader trade-proposals --json` | Inspect the manual-review proposal queue |\n| `agentic-trader proposal-candidates --json` | Inspect broker-free scanner/research candidates before proposal promotion |\n| `agentic-trader proposal-candidate-create ...` | Persist a candidate without approval or broker submission; adds redacted network-light provider context by default, with `--fetch-provider-news` as an explicit refresh opt-in |\n| `agentic-trader proposal-candidate-promote CANDIDATE_ID --json` | Promote a checked candidate into a pending manual-review proposal |\n| `agentic-trader proposal-create ...` | Queue a non-executing paper proposal for approval |\n| `agentic-trader proposal-approve PROPOSAL_ID --json` / `agentic-trader proposal-reject PROPOSAL_ID --reason \"...\" --json` | Approve or reject a pending proposal through the explicit manual-review gate |\n| `agentic-trader proposal-refresh PROPOSAL_ID --json` | Recheck an accepted broker order without resubmitting |\n| `agentic-trader proposal-reconcile PROPOSAL_ID --json` | Repair an in-flight proposal from a recorded execution outcome without resubmitting |\n| `agentic-trader idea-presets` / `agentic-trader idea-score ...` | Explore V1 idea-scanner presets without creating orders |\n| `agentic-trader strategy-catalog --json` / `agentic-trader strategy-profile NAME` | Inspect strategy-family evidence, risk, and validation gates |\n| `agentic-trader news-intelligence --symbol AAPL --json` | Build a source-tiered news/materiality research plan without fetching the web |\n| `agentic-trader research-cycle-plan --symbols AAPL,MSFT --json` | Inspect the safe PRE-FLIGHT/MONITOR/ANALYZE/PROPOSE/DIGEST cycle contract |\n| `agentic-trader research-cycle-run --symbols AAPL,MSFT --cycles 2 --no-sleep --json` | Run bounded evidence-only research cycles with preflight, source-health delta, cadence, and digest output but no broker authority |\n| `agentic-trader evidence-bundle --provider-check --json` | Package read-only QA/release evidence with active model/provider readiness |\n| `pnpm run qa:v1-paper-desk` | Run an isolated V1 paper-desk rehearsal with proposal and evidence artifacts |\n| `agentic-trader research-status --json` | Inspect optional research sidecar health |\n| `agentic-trader research-refresh --json` | Run one isolated sidecar snapshot pass |\n| `agentic-trader research-flow-setup --json` | Inspect optional CrewAI Flow sidecar readiness |\n| `agentic-trader review-run` | Review the latest persisted run |\n\n## Web GUI\n\n`webgui/` is a local command center for the existing runtime. It validates browser inputs, then calls the Python CLI/dashboard/runtime/chat/instruction/proposal contracts from server-side route handlers. It is intentionally not a second orchestrator, and its Proposal Desk can only call the same explicit approve/reject/reconcile/refresh gates that the CLI exposes.\n\nThe control-room UI is split into focused view, shell, dashboard-polling, `state-hooks`, `view-model`, action, `action-request`, request/auth, formatting, diagnostics/context evidence, loading-panel, primitive, and typed-copy modules under `webgui/src/components/control-room/`; keep new screen work on that modular path instead of growing the coordinator component again.\n\n```bash\npnpm dev:webgui\n```\n\n## Documentation\n\nThe docs app lives in `docs/` and is intended to deploy to GitHub Pages:\n\n[https://ogiboy.github.io/agentic-trader/](https://ogiboy.github.io/agentic-trader/)\n\nUse it for deeper setup, architecture, runtime, QA, frontend, and contribution guidance. Local development uses `pnpm dev:docs`.\n\n## Development\n\nThis repo favors small, inspectable changes over broad rewrites. Keep Python runtime behavior, Web GUI delegation, and docs content aligned.\n\n```bash\npnpm check\nmake check\npnpm run app:doctor\npnpm run app:up -- --dry-run\npnpm run app:setup -- --dry-run\npnpm run app:start -- --dry-run\npnpm run app:stop -- --dry-run\npnpm run app:update -- --dry-run\npnpm run app:uninstall -- --dry-run\npnpm run qa:quality\npnpm run setup:research-flow\npnpm run check:research-flow\npnpm run version:plan\npnpm run release:preview\npnpm run sonar:status\npnpm run mcp:sonarqube:status\npnpm run sonar\n```\n\n`pnpm check` is the canonical static/build validation entrypoint. Use `pnpm run qa` or `pnpm run qa:quality` for terminal smoke QA and operator-surface checks. The Makefile is a thin alias layer for developers who prefer `make setup`, `make check`, `make webgui`, `make docs`, or `make tui`.\n\nSonar is split by target on purpose:\n\n| Target | Project key | Use |\n| ------------------------------- | ----------------------- | ---------------------------------------------------------------- |\n| Local SonarQube Community Build | `agentic-trader` | Local Docker server, branch QA, Codex/MCP inspection |\n| SonarCloud | `ogiboy_agentic-trader` | GitHub-hosted CI, public badge, repository-level quality history |\n\n`sonar-project.properties` is the local default scanner file. `pnpm run sonar` runs the local Python scanner path through `pysonar`; `pnpm run sonar:js` runs the local npm scanner through `@sonar/scan`. Both read `SONAR_TOKEN` from the environment or macOS Keychain service `codex-sonarqube-token`. Use `pnpm run sonar:cloud` only when manually uploading to SonarCloud; it expects a SonarCloud token in `SONAR_TOKEN` or Keychain service `codex-sonarcloud-token`.\n\n`pnpm run sonar:start` waits until the local server is actually ready instead of only starting Docker containers. If an existing `sonarqube_postgres` volume was initialized with an older `SONAR_POSTGRES_PASSWORD`, the start/status scripts diagnose the password mismatch and suggest `pnpm run sonar:repair-db-password`, which aligns the stored local `sonar` database user password without deleting local Sonar history. If you provide `SONAR_AUTH_JWTBASE64HS256SECRET`, it must be Base64 encoded; unset it to use the repository's local-development default.\n\nUse `pnpm run secret:sonar:check`, `pnpm run mcp:sonarqube:dry-run`, or `pnpm run mcp:sonarqube:status` to verify the local Keychain/MCP wiring without printing tokens. The editor/Codex MCP wrapper uses `SONARQUBE_URL=http://host.docker.internal:9000` so Docker can reach the local host SonarQube server. Multiple running `mcp/sonarqube` containers usually mean multiple active MCP clients, not multiple SonarQube servers.\n\nGitHub Actions needs only `SONAR_TOKEN` as a repository secret for SonarCloud. Docs deployment uses GitHub Pages permissions, releases/binaries use the built-in `GITHUB_TOKEN`, and local Docker SonarQube tokens should stay on the developer machine.\n\nuv selects and syncs the root Python interpreter from `.python-version`, owns root dependency locking, command execution, and builds, while the tracked CrewAI Flow sidecar owns its own nested `uv.lock`. pnpm owns JavaScript workspace dependencies plus the shared command surface. The two uv projects intentionally stay separate below the root scripts so CrewAI can evolve without widening the core runtime dependency graph.\n\nCommit messages should follow conventional commits so release automation can infer version bumps:\n\n| Type | Example |\n| -------- | ------------------------------------------------- |\n| Feature | `feat: add docs deployment workflow` |\n| Fix | `fix: correct pyinstaller smoke build entrypoint` |\n| Docs | `docs: rewrite root readme` |\n| Breaking | `feat!: change release packaging flow` |\n\n`main` is the only branch that mutates `CHANGELOG.md` automatically. Product-impacting feature and V1 branch pushes still bump the tracked patch version across Python, workspace package manifests, sidecar metadata, and lockfile metadata before push so local artifacts identify the tested build clearly; `pnpm run version:plan` remains the branch preview check.\n\n## Uninstall / Cleanup\n\nNormal cleanup removes build/test/cache artifacts but keeps installed\ndependencies:\n\n```bash\npnpm run clean\n# or\nmake clean\n```\n\nRemove dependency installs explicitly when you want a fresh setup:\n\n```bash\npnpm run app:uninstall -- --dry-run\npnpm run app:uninstall -- --artifacts --deps --yes\n# or the older focused cleanup commands:\npnpm run clean:deps\n# or remove artifacts and dependencies together:\npnpm run clean:all\n```\n\nIf an older Poetry/Conda setup is still present, remove it separately:\n\n```bash\nconda remove -n trader --all\n```\n\n## License / Disclaimer\n\nAgentic Trader is released under the GNU Lesser General Public License v3.0 or\nlater (`LGPL-3.0-or-later`). See [LICENSE](LICENSE).\nBundled or adapted third-party helper components keep their own notices when\ntheir package metadata says so.\n\nAgentic Trader is a trading research and operator-tooling project with paper-first execution controls. It does not provide financial advice, and it must not be treated as an ungated live brokerage system. Real-money execution remains blocked unless a real adapter, explicit approval gates, and operator-visible safety checks are implemented and intentionally enabled.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogiboy%2Fagentic-trader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fogiboy%2Fagentic-trader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogiboy%2Fagentic-trader/lists"}