GitHub Trending

Hallmark A design skill for Claude Code, Cursor, and Codex that refuses to look AI-generated. Live demo → · twenty themes · four verbs · press T to cycle. Made by Together AI. Hallmark picks a macrostructure for the brief, dresses it in one of twenty themes, runs fifty-seven slop-test gates plus a pre-emit self-critique, and refuses the on-distribution defaults every LLM was trained into. Two pages by Hallmark for two different briefs feel like different sites, not colour-swaps of the same template. Four verbs | Verb | What it does | | --- | --- | | (default) | Build new UI. Picks a macrostructure, applies the rule-set, runs the slop test before handing back. | | hallmark audit | Score existing code against the anti-patterns. Punch list, no edits. | | hallmark redesign | Throw out the structure, keep copy + IA + brand, rebuild with a different fingerprint. | | hallmark study | Extract the DNA from a design you admire: macrostructure, type-pairing, colour anchor. Refuses pixel-clones and paid templates. Optionally emits a portable design.md for handoff to other AI tools. | Different briefs, different shapes Each generated from a different brief. The skill picks the theme, structure, and craft to fit each one, not from a template. BubbleSourdough app · Hum DistilExtraction API · Cobalt Cold SnapRecord label · Carnival CinderAI tool · Lumen Ferns & FathomTea menu · Custom Hollowback ApiaryHoney farm · Garden Off-RegisterPrint fair · Riso Press QuaternaryType studio · Custom TallySaaS · modern-minimal WayfareTravel · atmospheric NAJMFashion brand HyperlaneDev infrastructure Each page is self-contained HTML + CSS, stamped with its macrostructure in the CSS comment. Browse the full set at usehallmark.com or under site/_tests/. Custom NEW When a brief carries creative intent that no catalog theme fits, Hallmark switches to Custom and designs the page from scratch: a made-to-measure palette, type, and layout. Same 57 slop-test gates, no template underneath. The Cascadia NightjarSleeper-train ticket · Custom The Mend AssemblyRepair-café broadsheet · Custom It stays a quiet branch; vanilla briefs never see it. The protocol lives in custom-theme.md. Install npx skills add nutlope/hallmark Re-run any time to update. Or copy SKILL.md + references/ into: Claude Code: ~/.claude/skills/hallmark/ Cursor: .cursor/rules/hallmark.mdc (body of SKILL.md, no frontmatter) Codex: ~/.codex/skills/hallmark/ (personal) or .codex/skills/hallmark/ (project-scoped) The rule-set lives in SKILL.md and references/. Worked examples in docs/recipes.md and docs/study-examples.md. Licence MIT. Use it, fork it, ship it.

The open-source CapCut alternative

100+ AI Agent & RAG apps you can actually run — clone, customize, ship.

English | 中文 | 日本語 | 한국어 | العربية Vibe-Trading: Your Personal Trading Agent One Command to Empower Your Agent with Comprehensive Trading Capabilities Website · Docs · News · Features · Shadow Account · Demo · Quick Start · Examples · API / MCP · Roadmap · Contributing 📰 News ⚠️ Security warning: The X account VibeTrading_HKU, Virtuals project 101845, and token contract 0x640BDBF77b6447E8b7DB7894cED84BD1c40571f4 are not official Vibe-Trading assets. We have never launched or endorsed any token or memecoin. Do not buy, connect a wallet, or sign anything. Details. 2026-07-19 🔧 Real US/HK stock-news articles + MCP factor-analysis fix + a robustness pass: The stock-news tool now returns real Yahoo Finance articles (title/url/source/published/snippet) for US and HK tickers instead of related-instrument matches, still routed through the frozen IP-throttled client (#730, thanks @yxhuang). The MCP factor_analysis tool is realigned to the registered tool's real CSV contract, so calls no longer die on KeyError before running (#715, closes #635, thanks @Robin1987China). Plus a robustness pass: the whole Kimi K-series (k2/k3/…/for-coding) now auto-forces temperature=1 as the API requires (#701, thanks @sambazhu), and split_message, PDF page ranges, and trade-journal date filters all fail fast on degenerate or inverted input instead of hanging or silently returning nothing (#727–#729, thanks @santhreal). 2026-07-18 🔧 Binance crypto fallback + parallel-execution and correctness fixes: A Binance loader joins the crypto historical-data fallback chain (#643, thanks @tyj147454413-cmd), and the IBKR connector moves to a thread-local connection pool with snapshot quotes, fixing hangs under parallel agent runs (#636, thanks @MikeCer). Plus a correctness pass: factor analysis rejects non-positive n_groups, inverted period ranges and non-positive detection windows fail fast, an unnamed DatetimeIndex in the correlation matrix is handled, equity.csv nav/value column aliases are accepted, and empty A-share codes are no longer coerced to 000000.SZ (#709–#714, thanks @santhreal). A correlation-rewiring stability factor joins the academic zoo (#705, thanks @ebujinovch), the fundamental zoo is whitelisted for factor analysis (#707, thanks @sambazhu), persisted run state is now fsync-durable (#645, thanks @tyj147454413-cmd), and the dev extra installs the documented Black/Ruff toolchain (#634, thanks @xkam7ar). 2026-07-17 🧩 Correlation-regime skill + a broad backtest / data / live-safety correctness pass: a new correlation-regime detection skill (bundled skills → 88, #557, thanks @ebujinovch), a Longbridge runtime connection card (#569, thanks @fanfpy), and user-defined swarm presets loaded from ~/.vibe-trading (#570, thanks @darkknight4563). Plus hardening across the stack: silent-data-corruption fixes in the Futu / Tencent / CCXT / mootdx loaders, look-ahead-bias and strict-OOS guards in the factor bench and Shadow Account, live-trading safety (signed exposure caps, atomic daily order limits, consent-first mandate commits, fail-closed live state), and journal / QVeris-budget / swarm / CI-gate improvements (#552, thanks @xor-xe; much of the correctness work by @xkam7ar). Earlier news 2026-07-16 🔧 Dependency lock repaired + Windows settings save fix: the hash-verified runtime lock is regenerated so Docker's pip install --require-hashes resolves cleanly again, fixing the incompatible caio/pydantic-core/websockets pins (#564, closes #558, thanks @tianrking). Saving Agent LLM settings from the Web UI no longer returns HTTP 500 on Windows — the POSIX-only os.fchmod hardening is now platform-guarded, with a regression test for platforms without fchmod (#561, thanks @CRui5in). 2026-07-15 🧮 Backtest correctness + Portfolio Studio core: A 10-PR convergence pass made rebalances causal and order-independent, charged terminal close costs, reported fill-derived turnover, enforced exposure caps, and kept validation output finite and strict (#530/#531/#532/#540). Charts now reuse the run's actual data source, repeatable market queries are no longer dropped, and .env loads refresh cached config (#535/#544/#554). Portfolio Studio #456 and config bug #541 are closed; provider fixes #528/#529 closed too. Thanks @YZY0108, @santhreal, @Robin1987China, @xkam7ar, @Marnie0415, and @marichu99. 2026-07-14 🌉 Longbridge market data + modern MCP transport + provider reliability: Longbridge joins the historical-data fallback layer with key-gated credentials, date-window splitting, strict completeness checks, and an opt-in SDK dependency; four China-market flow tools gain verified Tushare fallbacks, and negative final equity no longer crashes backtest metrics. The MCP server now supports Streamable HTTP, write_file safely recovers aliased or missing path arguments, hypothesis updates reject unsupported fields, and Correlation requests are authenticated. NVIDIA NIM is now a first-class provider across Web Settings and both CLI onboarding paths, with a versioned compatibility User-Agent to address the reported 403; Web Settings now writes to the canonical ~/.vibe-trading/.env, migrates legacy configuration, and reports permission failures clearly, fixing the DeepSeek save-time 500 (#534, closes #516/#524; #528/#529). Thanks @fanfpy, @asahikiko, @santhreal, @sTunnaSu, @abhishekjaisinghani, @huangcheng, @ShiroKSH, @Meru143, @DIEGOD79, and @not-knope for the code, reports, and diagnosis. 2026-07-13 🔒 Security hardening: all 10 external-audit findings closed + contributor batch: every finding from the 2026-07-10 external security audit (issue #476, discussion #468) is now addressed on main — Docker multi-stage rebuild with digest-pinned images, an AST-hardened backtest sandbox blocking network/subprocess/eval/os.environ/unsafe-open (including inside nested function bodies), short-lived single-use SSE auth tickets, hardened Compose (read-only rootfs, dropped capabilities, resource limits), auth + rate limiting on /correlation, security headers, hash-locked dependencies, and more. Also merged: opt-in TAP mode for Alpaca key isolation (#377, thanks @0xZKnw), realized portfolio turnover surfaced in backtest metrics (#478, thanks @Robin1987China), a Frazzini-Pedersen betting-against-beta academic factor (Alpha Zoo → 461, #480, thanks @YogeshModi24), a look-ahead-bias fix across all 5 portfolio optimizers (#487, thanks @YZY0108), and two preflight/provider-config fixes (#479/#484, closes #477/#482, thanks @ananaymital/@Bortlesboat). 2026-07-12 🧪 Strategy Development Manager + contributor fix batch: the new strategy-dev-manager skill (#87) turns academic papers and broker research into registered factors/strategies with a persistent artifact store and automated IC/Sharpe decay monitoring — sdm_register / sdm_status / sdm_decay_scan drive an active → monitoring → decayed → disabled lifecycle over ~/.vibe-trading/ (#457, closes #455, thanks @shadowinlife). Also merged: the Correlation tab accepts bare tickers (AAPL,SPY) and walks the full loader fallback chain (#472, closes #471, thanks @yxhuang), the local loader honors requested intervals via OHLCV resampling (#467, thanks @Shizoqua), Binance USD-M perpetual history lands with explicit BTC-USDT-PERP routing + execution/mark price separation as the first #462 slice (#470, thanks @honginp), FastMCP transport imports now work across both module layouts (#469, thanks @roberttidball), and Requesty is available as an OpenAI-compatible LLM gateway provider (#474, thanks @Thibaultjaigu). 2026-07-11 🚀 v0.1.11 released (pip install -U vibe-trading-ai): rolls up three weeks since 0.1.10 — first-class Indian equity (NSE/BSE) backtesting, the PIT-safe fundamental factor layer (Alpha Zoo → 460), the 16-adapter IM channel runtime, end-to-end scheduled research, optional QVeris premium data, and today's contributor batch: a turnover-aware optimizer (#466, thanks @Robin1987China), an analyze_image vision tool + NapCat DM pairing + the IM-media read fix (#464/#463/#465, thanks @fei-moss), Longbridge Decimal serialization (#459, thanks @fanfpy), and packaged-manifest count guards (#461, thanks @asahikiko). Full details: CHANGELOG · release notes. 2026-07-10 🇮🇳 Indian equity (NSE/BSE) support + centralized env config: a dedicated IndiaEquityEngine lands — T+1 delivery, circuit bands, and a config-driven STT/stamp/exchange/SEBI/GST cost stack — with .NS/.BO symbol routing, an opt-in read-only Shoonya/Dhan data bridge, and 255 alpha101/qlib158 factors opted into the new equity_in universe (#305, thanks @muku314115). Environment variables now flow through a single Pydantic EnvConfig schema with an AST-based CI gate against future os.getenv sprawl (#440, closes #438, thanks @shadowinlife). Also: a second-confirmation dialog before committing a real trading mandate plus unified error toasts (#453, thanks @wison1717-maker), scheduled-research route tests (#452, thanks @Robin1987China), and GLM thinking models no longer lose their reasoning stream on the zhipu provider (#458). 2026-07-09 🧯 Docker startup unblocked + provider/CLI contributor batch: Docker/server startup no longer crashes when FastAPI route iteration sees an included-router-like entry without path (#450, thanks @Penn-Live). We also landed the queued quick-win contributor fixes: loader fetch() signatures now match the protocol across OKX / Tushare / yfinance (#437, thanks @shadowinlife), the CLI resume prompt preserves the first user message (#448, closes #447, thanks @morluto), Codex OAuth defaults to openai-codex/gpt-5.4 (#446, thanks @morluto), Kimi for Coding is available as a distinct provider (#435, thanks @yxhuang), opencode provider mappings are wired (#444, thanks @imsankz), and Tushare reference code fences now say python instead of pyhton (#449, thanks @flash1234pku). Validation included focused server/CLI/provider/loader tests plus a Docker build and /health smoke. 2026-07-08 💎 Fundamental factor layer (Phase 1) + optional QVeris premium data + maintainer day: PIT-safe SEC fundamentals now flow into daily factor panels — fund:* panel columns, filed-date anchoring with restatement and YTD-frame protection, and 4 new quality/value factors (registry now 460 alphas). Data routing gains an optional premium track: the 18 free sources stay the default, while QVeris unlocks 63+ providers via Settings → QVeris or vibe-trading data mode paid (see the QVeris section below). Also: api_server modularization completed (1,103 → 371 lines, #424 closing #331, thanks @shadowinlife), backtest validation.json no longer requires a pre-existing artifacts dir (#429, thanks @isaveall), clearer --swarm-run errors (#428, thanks @isaveall), and we reverted the governance stack that broke session chats (#433, thanks @yxhuang for the precise diagnosis). 2026-07-07 ✅ Contributor PR batch: merged the queued contributor work for IM channel timeout configuration (#413, thanks @SyntaxSawdust), Alpha Library social previews and the beginner tutorial (#396, #393, thanks @kadaliao), value-investing skills / tools / committee presets (#407, thanks @sambazhu), zero-sized order-field handling in trading_place_order (#417, thanks @irfanallana-oss), and timezone-aware UTC timestamps across session/API paths (#397, thanks @mustafakamal88). 2026-07-06 🧭 Preflight hardening, API slices, and CN search fallback: provider preflight no longer follows redirects (#404, closes #402, thanks @SyntaxSawdust), the remaining API routes moved into focused modules (#387, superseding #383-#386, thanks @shadowinlife), and CN web-search fallbacks now include Alibaba Cloud IQS (#408, thanks @sambazhu). Maintainer cleanup added no-network fallback tests and EOF whitespace cleanup (fbac74f); main CI is green (run 28780619018). 2026-07-05 ✅ Contributor PR queue closed + Windows baseline green: merged the four non-draft PRs selected for today's maintainer pass. A-share mootdx batch pulls now let KeyboardInterrupt / SystemExit propagate instead of being swallowed by a bare except (#399, closes #398, thanks @shadowinlife). The Settings route slice and patched dependency floors are now merged under their original contributor PRs (#382, #390, thanks @shadowinlife and @aeonframework). Windows baseline compatibility now isolates loader caches, makes OAuth cache assertions platform-aware, skips one fork-only mock test on Windows, and bypasses proxies for MCP loopback fixtures (#401, thanks @Elfsa-Miranda). Validation: 4701 passed, 47 skipped. 2026-07-04 🧩 API route slices, tutorial docs, and dependency floors: IM channel and Settings routes moved out of api_server.py into src/api/channels_routes.py and src/api/settings_routes.py, continuing the narrow #331 modularization path from contributor work (#379, #382, thanks @shadowinlife). The wiki gained a Chinese beginner tutorial for non-finance readers (#393, thanks @kadaliao), and dependency floors now keep Pillow / LangChain / LangGraph on the installable patched track (#390, thanks @aeonframework). 2026-07-04 🧹 UTC timestamp cleanup for session and API paths: tightened the #395 timestamp fix so session, goal, channel, and API timestamps now emit timezone-aware UTC values in explicit ISO form. 2026-07-03 🛡️ Robinhood MCP refresh + API modularization + SSRF guard: Robinhood Agentic Trading now uses the current MCP tool names across generic reads, live-runner plumbing, default read-only seeds, and mandate-gate tests, while interactive startup honors the same .env search order as the provider loader (~/.vibe-trading/.env → agent/.env → $CWD/.env) (#391, closes #381 and #380). System routes (/health, /correlation, /system/shutdown, /skills, /api) moved into src/api/system_routes.py as the next narrow API modularization slice (#378, thanks @shadowinlife). Channel media SSRF defenses now reject CGNAT/mesh/non-global targets and QQ media redirects-to-internal before fetching (#389, thanks @hobostay). 2026-07-02 ⚡ Factor acceleration + safer runtime boundaries: hot rolling factor operators now use bottleneck/NumPy fast paths, alpha bench parallelism avoids repeated large-panel worker payloads, and base equity math has regression coverage (#376, closes #339, original work from #342 by @shadowinlife). Upload and Shadow report routes moved out of the monolithic api_server.py as the first narrow API modularization slice while #331 stays open (#375, based on #358, thanks @shadowinlife). Generated backtests now inherit only an allowlisted subprocess environment instead of the parent secrets surface (#374, closes #332), and IM channels gained /new session reset plus case-insensitive pairing commands (#372, closes #371, thanks @shadowinlife). 2026-07-01 🧹 Security polish + tracker cleanup: tightened API/Docker/frontend dev defaults, stabilized Settings channel and zh-CN edges, cleared frontend dependency/CSP alerts, and closed stale WhatsApp + paper-trading tracker items (#338, #351, #349, #365, #367, #350, #335, #283). 2026-06-30 💬 IM channel runtime for research delivery: Vibe-Trading can now attach the same agent session runtime to 16 built-in message adapters — WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, and Mochat. CLI (vibe-trading channels status/start/stop/login/pairing), REST (/channels/status, /channels/start, /channels/stop, /channels/pairing/command), and the Web UI Settings panel expose status, recovery hints, start/stop, and sender pairing; SDK-backed adapters stay behind extras such as vibe-trading-aitelegram] or vibe-trading-ai[channels] ([#341). 2026-06-29 🛡️ Live advisory safety + Trading 212 read-only connector + Windows/Gemini fixes: live order guards now have an opt-in, broker-agnostic PreTradeAdvisoryInterface that records advisory reviews without bypassing the mandate gate, kill switch, or audit trail (#328, closes #317, thanks @shadowinlife). Trading 212 joins the connector layer with read-only account, positions, orders, history, and instrument-metadata support; place_order / cancel_order still hard-refuse until a structural paper/live boundary exists (#321, closes #309, thanks @mvanhorn). Windows startup avoids the pandas 3.0 Timestamp crash via the ` hint — so locating the trace for a finished run no longer means guessing which folder under agent/sessions/ is newest by timestamp. The new vibe-trading resume ` subcommand reopens that exact session and replays its recent turns into the loop; an unknown id fails fast instead of silently starting a blank session (#218, thanks @zwrong). 2026-06-12 🩺 Provider reliability overhaul — DeepSeek hangs, Kimi access, streaming liveness: A cluster of provider reports — DeepSeek runs stuck on "Agent is working…" (#208, thanks @XYWOX), reached max iterations masking empty model responses (#203, thanks @mojianliang), the UI never recovering after a stall (#195, thanks @mafia23), and Kimi rejecting the client (#204, thanks @liao497) — shared one root: every OpenAI-compatible provider ran through a single shim that applied DeepSeek/Kimi/Gemini quirks globally and silently swallowed stream failures. Provider-specific behavior now lives in an explicit capability layer — reasoning capture/replay, Gemini thought signatures, the Kimi User-Agent, OpenRouter's reasoning body are each gated to their own provider instead of cross-contaminating. Reasoning-only streams show a live "Reasoning…" indicator instead of dead air; a stream failure raises a contextual provider_stream_error with one automatic retry for transient resets (deterministic 4xx fail fast) instead of silently falling back to a slow non-streaming call; an empty model response is reported as empty_model_response instead of "max iterations"; SSE heartbeats no longer break reconnect replay; and a stuck read-only tool times out instead of hiding behind heartbeats forever. A new vibe-trading provider doctor prints a redacted provider/model/package/proxy snapshot for one-command triage of environment-side hangs. DeepSeek users can opt into the official native adapter with pip install "vibe-trading-aideepseek]", and kimi-k2.x's temperature=1 requirement is applied automatically — the Kimi path is verified end-to-end against the live API (tool calls + strict multi-turn reasoning replay on kimi-k2.6). 2026-06-11 🐝 Swarm workers now pull market data through the loader layer: An investment-committee run on NVDA exposed a chain of gaps — workers wrote ad-hoc yfinance scripts, trusted a malformed latest bar (volume present, OHLC empty), leaked NaN into non-strict JSON, and a context-free continuation prompt re-routed to the wrong preset ([#198, thanks @BillDin for an exceptional diagnosis plus both fixes). Swarm workers now get a local get_market_data tool backed by the same normalized loader registry as MCP — strict JSON, non-finite floats serialize as null — wired into every market-data preset (21 workers across 13 presets) with a prompt policy that steers OHLCV work tool-first (#199); run_swarm takes an explicit preset_name and refuses ambiguous continuation fragments instead of silently falling back to equity_research_team (#200). Grounding got smarter too: a bare US ticker like NVDA in a swarm prompt is promoted to NVDA.US (stopword-guarded), so workers start from authoritative pre-fetched prices. The tool joins the main agent registry as well — 48 tools now. Also: your Docker data now survives updates — persistent memory, the session search index, user-created skills, shadow accounts and broker config live in named volumes, so docker compose up --build no longer wipes them (#197, thanks @FlyerJ). 2026-06-10 🐳 Docker reaches a host-side Ollama out of the box: Inside the container localhost is the container itself, so the shipped OLLAMA_BASE_URL=http://localhost:11434 failed the LLM preflight for every Dockerized Ollama setup. docker-compose.yml now defaults to http://host.docker.internal:11434 (export OLLAMA_BASE_URL to point elsewhere) and adds the host-gateway extra_hosts mapping so the same file works on Linux as well as Docker Desktop (#196, thanks @ShahNewazKhan). 2026-06-09 🔑 Clearer error when the Web UI is opened from another machine: Reaching the chat from a non-loopback client (another machine, a VM host, a phone on your LAN) without API_AUTH_KEY set returned 403 on every sensitive endpoint — sending a message, listing sessions, live status — but the chat only showed a generic "Failed to send message, please retry." The send path now surfaces the real reason — "Remote API access requires an API key. Add it in Settings, or run the backend on localhost for local-only use." — and the README's web-UI setup spells out the localhost-vs-LAN rule plus the three fixes (browse via localhost on the same machine; set API_AUTH_KEY and enter it once in Settings; or VIBE_TRADING_TRUST_DOCKER_LOOPBACK=1 for Docker Desktop's host gateway) (#191, thanks @mafia23). 2026-06-08 🔧 Gemini 3.x multi-turn tool-calling fix: This completes the Gemini 3.x thinking-model fix. The 6/05 round-trip (#176) only covered in-memory history, but the real agent loop replays history as OpenAI-format dicts where LangChain dropped the per-tool-call thought_signature before the request was built — so multi-turn tool calling still 400'd with missing thought_signature. It is now re-attached at the single _convert_input chokepoint both invoke and stream pass through (parallel calls, where only the first of N is signed, included) (#184, thanks @ngoanpv). 2026-06-07 🐝 Live swarm status in the chat timeline: When the agent launches a multi-agent swarm (investment committee, quant desk, risk committee, …), the chat now renders an inline status card that streams each worker's state — waiting / running / done / failed / blocked / retrying — in real time, the same per-agent visibility the standalone swarm dashboard already had. Runtime events are bridged into the session SSE stream without changing the existing /swarm/runs API, and a finished card rehydrates from the final run_swarm result on reconnect or history replay (#188, thanks @BillDin). Preset routing also got sharper: an explicitly named preset (e.g. investment_committee, with or without underscores) now wins over keyword scoring, and the bare IV derivatives keyword no longer false-matches inside ordinary words like "given" (#189, thanks @BillDin). 2026-06-06 ⚖️ Alpha compare — head-to-head across CLI, Web UI, REST & agent: A new alpha compare benches a hand-picked shortlist of Alpha Zoo alphas against each other on a universe and period, then ranks them by IC mean/std, IR, IC-positive ratio or sample count — each with its gap to the leader. Unlike a full-zoo bench it evaluates only the alphas you name (a new run_bench(only=…) subset filter), so comparing three alphas no longer scores all 191 in their zoo. One shared core powers every surface: vibe-trading alpha compare … --sort ir (CLI), a Compare view in the Alpha Zoo Web UI (tick alphas in the catalogue → one-click compare with a streamed ranking table), POST /alpha/compare + SSE (REST), and a read-only alpha_compare agent tool (47 tools now). 2026-06-05 🇮🇳 Dhan + Shoonya connectors (India) — 10 brokers total: The connector-first trading layer adds Dhan and Shoonya for the Indian market (NSE/BSE equities + F&O), bringing the roster to ten brokers. Both are paper + read-only — like Longbridge, their APIs expose no runtime paper/live discriminator, so their place_order / cancel_order hard-refuse any non-paper config at the first line (the rule: a broker with no structural paper/live guard is capped at paper + read-only) (#181, closes #174). This cycle also fixes Gemini 2.5 / 3.x thinking models: their per-tool-call thoughtSignature now round-trips through the OpenAI-compatible path, so multi-turn function calling no longer fails with INVALID_ARGUMENT (#176, closes #170, thanks @mvanhorn & @jliu6789). Chinese docstrings landed on all 452 Alpha Zoo factors (#180, thanks @LeeCQiang), and a frontend test suite (197 vitest tests) plus backend auth / path-traversal / CORS security tests joined CI (#175, thanks @sambazhu). 2026-06-04 🗃️ Opt-in local data cache for all 7 data sources: A new VIBE_TRADING_DATA_CACHE switch lets every backtest loader — tushare, okx, ccxt, akshare, mootdx, yfinance, futu — cache settled historical bars under ~/.vibe-trading/cache (user home, never the repo), so repeated and long-horizon / cross-market backtests skip the network and avoid provider rate limits. Off by default. Batch and connection loaders (yfinance, futu) skip the bulk download / FutuOpenD connection entirely on a full cache hit, a staleness guard never caches a range ending today (its last bar is still forming), and cached frames round-trip byte-identical to freshly fetched ones (#177, thanks @mvanhorn). A new contributor guide for AI / automation-assisted PRs also landed, mapping safe local checks and high-risk broker/MCP/credential surfaces (#173). 2026-06-03 🧹 Community triage + trace correlation: Tool-call trace entries now carry the originating call_id, so a tool_result can be matched back to its tool_call when replaying a run trace — arg previews stay truncated to keep trace files small (#168, thanks @zwrong). Source comments no longer point at an internal-only docs path that external contributors couldn't find (#166, thanks @jaleelpersonal). Also clarified that the langchain-community resolver warning on install is a harmless leftover-package notice, not a failure (#167), and scoped Gemini 2.5/3.0 thoughtSignature round-tripping for function calls as a help wanted task with a full fix plan (#170, thanks @jliu6789). 2026-06-02 🔌 Six new broker connectors (Tiger / Longbridge / Alpaca / OKX / Binance / Futu): The connector-first trading layer gains a direct-SDK transport alongside IBKR (local) and Robinhood (MCP). Each connector exposes read-only account / positions / orders / quote / history plus paper-account order placement — test your strategies across these broker paper accounts. Five of them (Tiger, Alpaca, OKX, Binance, Futu) also support bounded, mandate-gated order placement behind the same safety model as Robinhood: a user-committed mandate (symbol universe / order size / exposure / leverage / daily cap), a filesystem kill switch, a fail-closed pre-trade gate, and a full audit ledger. Longbridge is paper + read-only only (its API exposes no runtime paper/live discriminator). Every paper/live distinction is a structural per-broker guard — account-id format, host separation, demo flag, or trade environment. New trading_place_order / trading_cancel_order tools; HK and A-share asset classes added to the mandate universe. Experimental / use at your own risk. 2026-06-01 🚀 v0.1.9 released (pip install -U vibe-trading-ai): Rolls up everything since 0.1.8. Connector-first broker profiles (IBKR local read-only TWS / IB Gateway + Robinhood Agentic Trading behind OAuth, a committed mandate, order guard, audit ledger, and instant halt). Research Goal runtime across CLI / REST / MCP / Web. A swarm pass — live reconcile + MCP keepalive, operator-configured worker MCP tools, a strict alpha-bench random control, and a new retry_run to relaunch failed/stale runs (36 MCP tools now). The agent/cli/ package refactor with a refreshed terminal UI, the mootdx no-token A-share loader, and a robustness pass across backtest / agent loop / sessions. --version now always matches the installed package, fixing the 0.1.8 drift (#156). 2026-05-31 🔌 Connector-first broker architecture (IBKR + Robinhood): Trading access now starts from a selectable connector profile instead of separate broker/live entry points. vibe-trading connector list/use/check/account/positions/orders/quote/history and the MCP trading_* tools share the same selected profile, where paper/live is an attribute of the connector. IBKR can be used immediately through a local read-only TWS / IB Gateway profile, while the official IBKR remote MCP path is seeded as an OAuth mcp.read probe until stable read tool names are available. Robinhood Agentic Trading remains the bounded live MCP connector behind OAuth, a committed mandate, order guard, audit ledger, and instant halt. 2026-05-30 🧰 Robustness pass — backtest, agent loop, sessions: LLM-generated signal engines now pass pre-flight interface validation before instantiation, catching circular self-imports, a missing generate(), non-defaulted init args, and wrong return types with actionable JSON errors instead of raw tracebacks (#149); a follow-up routes source-level AST validation errors through the same clean JSON envelope. The agent loop no longer burns all 50 iterations into a failed status with no output — it mirrors the swarm worker's wrap-up nudge at 80% of the iteration budget and drops tool definitions on the last iteration to force a final text answer (#148), guarded to fire only mid-run so it never displaces research-goal context. Session message writes now flush + fsync each append so expensive AI responses survive a mid-write crash, and the read path skips corrupted JSONL lines (logging the first 200 chars for recovery) instead of 500-ing the whole /messages endpoint (#147). The Web composer also fixes IME Enter handling so a composition-confirming Enter no longer submits mid-word (#146). 2026-05-29 🔐 Robinhood Agentic Trading support (opt-in, bounded autonomy): Adds support for Robinhood Agentic Trading (remote MCP, OAuth). Off and read-only by default; the agent acts only inside a user-committed mandate (symbols / order size / exposure / leverage / daily cap), with a filesystem-level instant kill switch, preemptive flatten, mandate auto-expiry, a full audit ledger, and a persistent autonomous runner. No custody, no venue — the broker holds funds and executes; we only relay intent. Experimental / use at your own risk. 2026-05-28 🧪 Swarm safety + strict alpha gate + worker MCP: Swarm DAG blocks downstream tasks when upstream fails (#145). New run_bench_strict() adds a same-universe random control + OOS split to catch factors that just track market beta (#143, thanks @Soli22de). Swarm workers can call operator-configured external MCP servers, with trust boundary pinned (#142, thanks @shadowinlife). 2026-05-27 📊 mootdx A-share data source + output polish: New mootdx loader speaks the native 通达信 TCP protocol for A-share OHLCV (no auth, no IP rate-limit, daily + intraday with 25-page walk-back pagination), slotting between tushare and akshare in the fallback chain (#107). CCXT loader now reads HTTP_PROXY/HTTPS_PROXY/ALL_PROXY so Binance/OKX public data works from restricted networks (#126, thanks @ruok808). Final-answer rendering also dropped the ugly full-width --- horizontal separators on CLI and Web: the system prompt now nudges the agent toward markdown tables and ## headings, the CLI renderer strips standalone HRs as defense-in-depth, and the chat bubble hides any `` that slips through (#139, thanks @sdwxm188). 2026-05-26 ✅ Research Goal lifecycle closure: Goal mode now behaves like a real task runner: Web UI goal creation creates or binds the session and immediately sends the kickoff turn; active goals can be continued, edited, cancelled, and completed across Web/API/CLI/MCP; and the agent advances from the current goal snapshot (criteria, evidence, claims, open items) instead of only the original prompt. Covered-but-still-active goals now enter an audit/status update instead of stopping silently, with regression coverage across backend, CLI, MCP, and frontend events. 2026-05-25 🧼 Cleaner chat UI + composer workflow: The Web UI keeps chat focused on the next action: upload, swarm, and research-goal modes now live behind the composer + menu instead of floating panels. Active context appears above the input as compact chips, and goal details expand inline only when needed. The UI also drops the old custom i18n layer in favor of direct English copy, gates Full Report cards to report-worthy runs, and hardens local dev startup/status reporting for reliable browser smoke tests. 2026-05-24 🎯 Research Goal runtime: Added a session-scoped Research Goal layer across backend, CLI, API/MCP, SSE, and Web UI. Goals persist claims, acceptance criteria, evidence rows, budgets, and completion policy; agent tools can create goals and attach evidence; /goal gives the CLI a direct entry point; REST/MCP expose goal snapshots and evidence writes; SSE keeps chat clients fresh. Follow-up audit fixes locked down verified evidence, blocked live-trading risk tiers through agent tools, wired CLI-created goals into later turns, cleaned goal ledgers on session deletion, enabled replay-all, and fixed cross-session frontend races. 2026-05-23 🖥️ Interactive CLI refresh: The terminal front door now opens with a larger Vibe-Trading banner, a cleaner prompt divider, prior-turn recap, post-run timing, and a Claude Code-style activity rail for live agent work. Tool calls, web/data fetches, shell-style actions, Markdown answers, and pipe tables render in a more readable transcript, while piped or non-TTY runs keep plain-text output for automation. Generated CLI screenshots are now treated as local artifacts instead of committed docs files, keeping the repository lighter. 2026-05-22 🧭 Swarm recovery + MCP keepalive: Swarm status now reconciles from live task files on every read, so API/MCP/SSE/list views recover crashed or stale runs instead of showing permanent running snapshots. run_swarm sends MCP progress heartbeats while it polls, with a fixed first frame of swarm_started run_id= for clients that reconnect after transport drops; workers now heartbeat through LLM streaming, grounding fetches, and tool execution. The stale-run reaper uses per-run thresholds and derives terminal status from task states, SwarmTool no longer cancels a still-running team just because its wait budget elapsed, and MCP clients can call reap_stale_runs() for explicit cleanup. Today's DX pass also refreshed provider default models and aligned CI syntax checks with the new agent/cli/ package. 22 new regressions cover hydration, terminal recovery, stale reaping, keepalive cadence, env parsing, and heartbeat wiring; the full swarm/MCP suite is at 169 passed, 4 skipped. 2026-05-21 🧱 CLI package refactor: agent/cli.py (3216 LOC) split into the agent/cli/ package — interactive front door, slash router, Rich components, plus a legacy.py shim that preserves every subcommand and re-exports every public symbol so cli.cmd* / cli.INIT_ENV_PATH / cli.Confirm keep working. New FastAPI middleware serves the SPA shell when a browser opens /runs/{id} or /correlation directly; same narrowing landed in the Vite dev proxy. Version unified via cli/_version.py (no more drift between --version and the banner), python -m cli restored via __main_.py, and the chat-gate narrowed so chat --help / chat extra reach legacy argparse instead of being swallowed by the REPL. 2026-05-20 🔬 Hypothesis Registry CLI: Closes the CLI side of the Hypothesis Registry shipped backend-only on 2026-05-16. vibe-trading hypothesis list prints a Rich table or JSON (--status filter, --limit); show renders a detail panel including linked run cards; invalidate --note "..." flips status to rejected while preserving prior invalidation notes when --note is omitted. Honors the existing VIBE_TRADING_HYPOTHESES_PATH env override and adds a per-invocation --path. 22 new tests cover wiring, JSON output, status filter, limit, missing-id errors, and note persistence. 2026-05-19 ✨ Live tool feedback + graceful cancel: Long-running tools (backtests, large PDFs, swarm workers) no longer look frozen. Each tool call now emits a 3-second heartbeat plus structured per-stage progress — run_backtest shows phase markers (validate / simulate / finalize), read_document ticks per page on PDF or per sheet on Excel, read_url marks fetch / parse. The CLI Rich Live dashboard renders a Unicode spinner, ASCII progress bar, ETA, and stacks up to 3 parallel tools keyed by name; the frontend chat ships a new ToolProgressIndicator with rAF-coalesced renders, ARIA role="status" + hidden native ` for screen readers, and a determinate ProgressRing SVG when total is known. First Ctrl+C during a CLI run now calls agent.cancel() for graceful exit (current step finishes, trace closes cleanly); a second within 2s force-quits. Reusable primitives extracted along the way: ProgressBar.tsx and lib/tools.ts` (shared tool-name i18n). 2026-05-18 🧹 Cleanup pass + three latent bug fixes: CompositeEngine no longer misroutes bare Chinese-futures codes like RB2410 to GlobalFuturesEngine — _is_china_futures moved into a shared _market_hooks module with a case-normalized product table and a non-CN exchange guard, plus 9 new regression cases. Session FTS5 indexes now persist timestamps so cross-session search can sort by date; the same path also fixed a re-upsert that was wall-clocking every session's started_at. The Vite dev-mode proxy gained the missing /alpha entry so the AlphaZoo page resolves on npm run dev. tests/test_e2e_harness_v2.py (real-LLM e2e suite) is now gated behind VIBE_TRADING_RUN_LIVE_E2E=1 so CI no longer changes shape based on env-key presence. Ruff per-file-ignores added for the factor zoo (3783 → 0 F401 noise), frontend tsconfig enables noUnusedLocals / noUnusedParameters as regression guards, and 76 unused vw = vwap(...) boilerplate lines were dropped from gtja191 alphas. Net -918 LOC. 2026-05-17 🧬 Alpha Zoo v1 (0.1.8): 452 pre-built quant alphas across 4 zoos — qlib158 (Microsoft Qlib, Apache-2 attribution), alpha101 (Kakushadze 101 Formulaic Alphas, paper rewrite from arXiv:1601.00991), gtja191 (Guotai Junan 2014 short-horizon factor report), and academic (Fama-French 5 + Carhart price-based proxies). One-line CLI to bench any zoo on your universe: vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025. Ships with AST purity gate, lookahead-guard test, pytest-socket network kill-switch, per-zoo LICENSE.md, and a Developer Certificate of Origin (DCO) workflow for community PRs. Auto-rendered Alpha Library at vibetrading.wiki/alpha-library/ + research-lab post Which of the 191 GTJA alphas still work in 2026?. 2026-05-16 🧪 Research spine update: Added a backend Hypothesis Registry with create_hypothesis, update_hypothesis, link_backtest, and search_hypotheses; external-content readers now attach warning-only security_warnings; and Shadow Account scanning now uses deterministic OHLCV feature evaluation instead of the old calendar-phase stub. 2026-05-15 🪪 The run detail page now surfaces the Trust Layer run card alongside metrics and artifacts, completing the UI side of the run_card.json work landed on 2026-05-12. PersistentMemory.add() was also hardened on length, empty/whitespace-only names, and C0/C1 control bytes from the #108/#109/#110 triage (#112, thanks @Teerapat-Vatpitak). 2026-05-14 🌐 the public wiki is now live at vibetrading.wiki with docs, tutorials, Research Lab, and Alpha Library sections deployed through Cloudflare Pages. Persistent memory is also inspectable from the CLI via vibe-trading memory list/show/search/forget (#102, thanks @Teerapat-Vatpitak), and memory tokenization/slugs now support Thai, Arabic, Hebrew, and Cyrillic text (#104). 2026-05-13 🧭 Swarm runs now ground workers with fetched market data and cleaner persisted reports (#93, #84). 2026-05-12 🧾 Backtests now emit run_card.json and run_card.md alongside artifacts for reproducible research runs. 2026-05-11 🧭 Memory slugs, swarm accounting, and CLI preflight: Persistent memory now preserves CJK characters when generating file slugs, preventing silent filename collisions for Chinese/Japanese/Korean notes (#95, thanks @voidborne-d). Swarm run totals now prefer provider-reported token usage with the existing estimate fallback (#94, thanks @Teerapat-Vatpitak), and the CLI run UI gained a startup preflight check for common environment issues (#96, thanks @ykykj). 2026-05-10 🧱 Regression guardrails + run metadata: Memory recall now treats underscores as token boundaries, so snake_case saved memories such as mcp_wiring_test match natural-language queries like "mcp wiring" (#87, thanks @hp083625). The MCP server has a subprocess smoke test covering initialize → tools/list → tools/call to guard the first-call deadlock path (#86), while low-risk hardening landed for Windows path-sensitive tests, API best-effort exception handling, backtest run_dir allowed-root validation, and SwarmRun provider/model metadata (#88, #90, #91, #92, thanks @Teerapat-Vatpitak). 2026-05-09 🛡️ API path hardening + MCP server stability: API run/session routes now validate path IDs before lookup, rejecting malformed newline-containing parameters and pinning the behavior in the auth/security regression suite (#80, thanks @SJoon99). The MCP server now pre-warms the tool registry on the main thread before serving tools/call, avoiding a first-call deadlock in lazy tool discovery (#85, thanks @Teerapat-Vatpitak). The Vite dev proxy also honors VITE_API_URL for non-default backend targets (#82, thanks @voidborne-d). 2026-05-08 🧾 Tushare statement fields in filters: A-share daily backtests can now request PIT-safe financial statement fields through fundamental_fields, so signal engines can screen on income_total_revenue, income_n_income, balancesheet_total_hldr_eqy_exc_min_int, fina_indicator_roe, and similar table-prefixed columns after their announcement/disclosure dates (#76, thanks @mrbob-git). Follow-up hardening makes explicit statement-field requests fail fast if Tushare enrichment cannot run, instead of silently falling back to raw price bars (#77). 2026-05-07 📈 Tushare fundamentals + community triage: Added a point-in-time TushareFundamentalProvider contract for fundamental research workflows, with regression coverage for the project TUSHARE_TOKEN environment path (#74). Community triage also clarified that Vibe-Trading keeps rapid iteration focused on one UI language for now, avoids adding redundant search dependencies while DuckDuckGo-backed web_search is already bundled, and treats unofficial hosted deployments as untrusted places for API keys or data-source tokens. 2026-05-06 🚀 v0.1.7 released (Release notes, pip install -U vibe-trading-ai): Security-boundary hardening is now published on PyPI and ClawHub, covering safer API/read/upload/file/URL/generated-code/shell-tool/Docker defaults while keeping localhost CLI/Web UI workflows low-friction. This cycle also includes Web UI Settings, correlation heatmap, OpenAI Codex OAuth, A-share pre-ST filtering, interactive CLI UX, swarm preset inspection, dividend analysis, dev workflow polish, and audited frontend build-dependency floors. Thanks to the 0.1.7 contributors and to lemi9090 (S2W) for coordinated security validation. 2026-05-05 🛡️ Security boundary follow-up: Completes the remaining security-boundary hardening around explicit CORS origins, Settings credential indicators, web URL reading, and Shadow Account code generation, with regression tests added for each path. Normal localhost CLI/Web UI workflows stay the same; remote deployments should continue using API_AUTH_KEY and explicit trusted origins. 2026-05-04 🖥️ Interactive CLI UX + CI cleanup: Interactive mode now has a live bottom status bar showing provider/model, session duration, last-run latency, and cumulative tool-call stats, plus prompt history navigation and cursor editing with arrow keys via prompt_toolkit (#69). The CLI still falls back to Rich prompts when prompt_toolkit or a TTY is unavailable. CI path expectations were also aligned with the hardened file-import sandbox and cross-platform /tmp resolution, returning main to green (bb67dc7). 2026-05-03 🛡️ Security hardening patch: Tightens default API authentication for non-local deployments, protects sensitive run/session/swarm reads, restricts upload and local file-reading boundaries, gates shell-capable tools by entry point, validates generated strategy loading before import, and runs the Docker image as a non-root user with a localhost-only published port by default. Local CLI and localhost Web UI workflows remain low-friction; remote API/Web deployments should set API_AUTH_KEY. 2026-05-02 🧭 Dividend analysis + sharper roadmap: Added the dividend-analysis skill for income stocks, payout sustainability, dividend growth, shareholder yield, ex-dividend mechanics, and yield-trap checks, pinned by bundled-skill regression tests. The public roadmap now focuses on upcoming work: Research Autopilot, Data Bridge, Options Lab, Portfolio Studio, Alpha Zoo, Research Delivery, Trust Layer, and Community sharing. 2026-05-01 🔥 Correlation heatmap + OpenAI Codex OAuth + A-share pre-ST filter: New correlation dashboard/API computes rolling return correlations and renders an ECharts heatmap for portfolio and symbol analysis (#64). OpenAI Codex provider support now uses ChatGPT OAuth via vibe-trading provider login openai-codex, with Settings metadata and adapter regression tests (#65). Added and hardened the ashare-pre-st-filter skill for A-share ST/*ST risk screening, including Sina penalty relevance filtering so securities-account mentions do not inflate E2 counts (#63). 2026-04-30 ⚙️ Web UI Settings + validation CLI hardening: New Settings page for LLM provider/model, base URL, reasoning effort, and data source credentials, backed by local/auth-protected settings APIs and data-driven provider metadata (#57). Also hardens python -m backtest.validation so missing, blank, malformed, non-existent, and non-directory inputs fail with clear operator-facing messages before validation starts (#60). 2026-04-28 🚀 v0.1.6 released (pip install -U vibe-trading-ai): Fixes vibe-trading --swarm-presets returning empty after pip install / uv tool install (#55) — preset YAMLs now bundled inside the src.swarm package and pinned by a 6-test regression suite. Plus AKShare loader correctly routes ETFs (510300.SH) and forex (USDCNH) to the right endpoints with hardened registry fallback. Rolls up everything since v0.1.5: benchmark comparison panel, /upload streaming + size limits, Futu loader (HK + A-share), vnpy export skill, security hardening, frontend lazy loading (688KB → 262KB). 2026-04-27 📊 Benchmark panel + upload safety: Backtest output now ships a benchmark comparison panel (ticker / benchmark return / excess return / information ratio) with yfinance-backed resolution for SPY, CSI 300, etc. (#48). Plus /upload streams the request body in 1 MB chunks and aborts past MAX_UPLOAD_SIZE, bounding memory under oversized/malformed clients (#53) — pinned by a 4-case regression suite. 2026-04-22 🛡️ Hardening + new integrations: Path containment enforced in safe_path + journal/shadow tool sandbox, MANIFEST.in ships .env.example / tests / Docker files in sdist, route-level lazy loading shrinks frontend initial bundle 688KB → 262KB. Plus Futu data loader for HK & A-share equities (#47) and vnpy CtaTemplate export skill (#46). 2026-04-21 🛡️ Workspace + docs: Relative run_dir normalized to active run dir (#43). README usage examples (#45). 2026-04-20 🔌 Reasoning + Swarm: reasoning_content preserved across all ChatOpenAI paths — Kimi / DeepSeek / Qwen thinking work end-to-end (#39). Swarm streaming + clean Ctrl+C (#42). 2026-04-19 📦 v0.1.5: Published to PyPI & ClawHub. python-multipart CVE floor bump, 5 new MCP tools wired (analyze_trade_journal + 4 shadow-account tools), pattern_recognition → pattern registry fix, Docker dep parity, SKILL manifest synced (22 MCP tools / 71 skills). 2026-04-18 👥 Shadow Account: Extract your strategy rules from a broker journal → backtest the shadow across markets → 8-section HTML/PDF report showing exactly how much you leave on the table (rule violations, early exits, missed signals, counterfactual trades). 4 new tools, 1 skill, 32 tools total. Trade Journal + Shadow Account samples now live in the web UI welcome screen. 2026-04-17 📊 Trade Journal Analyzer + Universal File Reader: Upload broker exports (同花顺/东财/富途/generic CSV) → auto trading profile (holding days, win rate, PnL ratio, drawdown) + 4 bias diagnostics (disposition effect, overtrading, chasing momentum, anchoring). read_document now dispatches PDF, Word, Excel, PowerPoint, images (OCR), and 40+ text formats behind one unified call. 2026-04-16 🧠 Agent Harness: Persistent cross-session memory, FTS5 session search, self-evolving skills (full CRUD), 5-layer context compression, read/write tool batching. 27 tools, 107 new tests. 2026-04-15 🤖 Z.ai + MiniMax: Z.ai provider (#35), MiniMax temperature fix + model update (#33). 13 providers. 2026-04-14 🔧 MCP Stability: Fixed backtest tool Connection closed error on stdio transport (#32). 2026-04-13 🌐 Cross-Market Composite Backtest: New CompositeEngine backtests mixed-market portfolios (e.g. A-shares + crypto) with shared capital pool and per-market rules. Also fixed swarm template variable fallback and frontend timeout. 2026-04-12 🌍 Multi-Platform Export: /pine exports strategies to TradingView (Pine Script v6), TDX (通达信/同花顺/东方财富), and MetaTrader 5 (MQL5) in one command. 2026-04-11 🛡️ Reliability & DX: vibe-trading init .env bootstrap (#19), preflight checks, runtime data-source fallback, hardened backtest engine. Multi-language README (#21). 2026-04-10 📦 v0.1.4: Docker fix (#8), web_search MCP tool, 12 LLM providers, akshare/ccxt deps. Published to PyPI and ClawHub. 2026-04-09 📊 Backtest Wave 2: ChinaFutures, GlobalFutures, Forex, Options v2 engines. Monte Carlo, Bootstrap CI, Walk-Forward validation. 2026-04-08 🔧 Multi-market backtest with per-market rules, Pine Script v6 export, 5 data sources with auto-fallback. ✨ Key Features 🔍 Self-Improving Trading Agent • Natural-language market research • Strategy drafts and file/web analysis • Memory-backed workflows 🐝 Multi-Agent Trading Teams • Investment, quant, crypto, and risk teams • Streaming progress and persisted reports • Workers grounded with fetched market data 📊 Cross-Market Data & Backtesting • A/HK/US equities, crypto, futures, and forex • Data fallback and composite backtests • PIT data, validation, and run cards 👥 Shadow Account • Broker-journal behavior diagnostics • Rule-based Shadow Account comparisons • Exportable audit reports and strategy code 💡 What Is Vibe-Trading? Vibe-Trading is an open-source research workspace for turning finance questions into runnable analysis. It connects natural-language prompts to market-data loaders, strategy generation, backtest engines, reports, exports, and persistent research memory. It is designed for research, simulation, and backtesting — and, when you choose, autonomous trading through a broker you authorize yourself (e.g. Robinhood Agentic Trading). It holds no funds and never trades outside the limits you set, and you can halt it instantly. ✨ What You Can Do | Task | Output | |------|--------| | Ask a trading question | Market research with tools, data, documents, and reusable session context. | | Backtest a strategy idea | Strategy code, metrics, benchmark context, validation artifacts, and run cards. | | Review your own trades | Broker-journal parsing, behavior diagnostics, rule extraction, and Shadow Account comparisons. | | Improve repeated research | Persistent memory and editable skills turn useful routines into reusable workflows. | | Run analyst teams | Multi-agent research reviews for investment, quant, crypto, macro, and risk workflows. | | Put research into IM channels | Run the same session runtime through WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, and Mochat with CLI, REST, and Web UI controls. | | Ship usable artifacts | Reports, TradingView Pine Script, TDX, MetaTrader 5, MCP tools, and later research sessions. | | Bench a pre-built alpha zoo | One-line IC + alive/reversed/dead categorisation across 461 alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental) on your universe. | ⚡ Quick Example pip install vibe-trading-ai Natural-language research vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024, summarize return and drawdown, then export the report" Bench a pre-built alpha zoo (one line) vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20 vibe-trading --upload trades_export.csv vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, and compare it with my actual trades" 👥 Shadow Account Shadow Account starts from your own trading records instead of a generic strategy template. Upload a broker export, let the agent summarize your behavior, then compare the actual trading path with a rule-based shadow strategy. | Step | Agent output | |------|--------------| | 1. Read your journal | Parses broker exports from 同花顺, 东方财富, 富途, and generic CSV formats. | | 2. Profile your behavior | Holding days, win rate, PnL ratio, drawdown, disposition effect, overtrading, momentum chasing, and anchoring checks. | | 3. Extract your rules | Turns recurring entries/exits into an explicit strategy profile instead of a hand-wavy summary. | | 4. Run the shadow | Backtests the extracted rules and highlights rule breaks, early exits, missed signals, and alternative trade paths. | | 5. Deliver the report | Produces an HTML/PDF report that can be inspected, archived, or refined in a later session. | vibe-trading --upload trades_export.csv vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, and compare it with my actual trades" 🧪 Research Workflow Most runs follow the same evidence path: route the request, load the right market context, execute tools, validate outputs, and keep the artifacts inspectable. | Layer | What happens | |-------|--------------| | Plan | Selects the relevant finance skills, tools, data sources, and swarm preset when useful. | | Ground | Pulls A-shares, HK/US equities, crypto, futures, forex, documents, or web context through the available loaders. | | Execute | Generates testable strategy code, runs tools, and uses the matching backtest engine or analysis workflow. | | Validate | Adds metrics, benchmark comparison, Monte Carlo, Bootstrap, Walk-Forward, run cards, and warnings where applicable. | | Deliver | Returns reports, artifacts, tool traces, and exports for TradingView, TDX, MetaTrader 5, MCP clients, or later sessions. | 📡 Data Sources & Smart Fallback One get_market_data call, 19 free market-data sources (plus the optional QVeris premium marketplace). Set source: "auto" — the loader picks by symbol, then walks a per-market chain ordered by IP-ban risk: never-banned public sources first, throttled / key-gated ones last. Zero config, no single point of failure. | Source | Markets | Auth | Role | |--------|---------|------|------| | tencent · mootdx | A-share | none | never IP-banned (mootdx = 通达信 TCP) | | eastmoney | A / US / HK | none | OHLCV + deep fundamentals & flow tools (throttled) | | baostock · akshare | A (+ US/HK/futures/macro/fx) | none | free fallbacks | | tushare | A / futures / fund / macro | token | richest A-share | | yahoo · sina · stooq | US (/HK) | none | direct chart/quotes/options · K-line to 1984 · EOD CSV | | yfinance | US / HK | none | wrapper | | longbridge | US / HK | App Key + App Secret + Access Token | optional historical OHLCV source; install the optional SDK | | finnhub · alphavantage · tiingo · fmp | US | key | optional providers | | qveris | global multi-asset | key · credits | premium marketplace — 63+ providers via one key (explicit-only, never in auto fallback) | | okx · ccxt | crypto | none | OKX + 100+ exchanges | | futu | HK / A | OpenD | optional local FutuOpenD | | india_broker | India (NSE/BSE) | broker login | read-only Shoonya / Dhan bars for .NS / .BO (fallback-chain tail) | | local | any | none | your own CSV / Parquet / DuckDB via local: prefix | Fallback chains (by IP-ban risk): A-share → tencent · mootdx · eastmoney · baostock · akshare · tushare · local US → yahoo · stooq · sina · eastmoney · yfinance · tiingo · fmp · finnhub · alphavantage · longbridge · akshare · local HK → eastmoney · yahoo · futu · yfinance · akshare · longbridge · local India (NSE/BSE) → yahoo · yfinance · india_broker · local Crypto → okx · ccxt · yfinance · local · (futures / fund / macro / forex → tushare/akshare → local) Using Longbridge explicitly Longbridge is an optional US/HK historical OHLCV loader. Install its SDK with: pip install "vibe-trading-ailongbridge]" Configure the three credentials in .env: LONGBRIDGE_APP_KEY=... LONGBRIDGE_APP_SECRET=... LONGBRIDGE_ACCESS_TOKEN=... For a backtest, set source in config.json: { "codes": ["QQQ.US"], "start_date": "2025-01-01", "end_date": "2025-01-10", "interval": "1D", "source": "longbridge" } In an Agent conversation, ask explicitly: "Use Longbridge to fetch QQQ.US historical data." The explicit source request is separate from source: "auto"; auto keeps the normal per-market fallback chain. Beyond OHLCV, 18 read-only data tools reach into fundamentals & flow — fund flow, dragon-tiger, northbound, margin, block trades, shareholder count, lockup, sector, research reports, news, SEC filings, financial statements, options chains, institutional holdings, market screening, symbol search, and macro — all exposed over MCP. An explicit local: symbol never silently falls back to a network source. 💎 Optional premium data — QVeris Data: free routing or premium, your choice. Free stays the default: 19 built-in sources with ban-risk fallback, no key, no cost. Premium via QVeris adds 10,000+ capabilities (per QVeris) across 63+ providers for options Greeks, premium fundamentals, China/HK/global data, macro, crypto, news, and filings; failed calls are not charged. Enable it in Settings -> QVeris or vibe-trading data mode paid. QVeris disclosure: [signing up through the Vibe-Trading referral link gets you *+1,000 bonus credits* and supports the project. 🔩 Detailed Capabilities Detailed inventories are folded below to keep the main README scannable. Open them when you want to inspect the available building blocks. Finance Skill Library 87 skills across 9 categories 📊 87 specialized finance skills organized into 9 categories 🌐 Complete coverage from traditional markets to crypto & DeFi 🔬 Comprehensive capabilities spanning data sourcing to quantitative research | Category | Skills | Examples | |----------|--------|----------| | Data Source | 10 | data-routing, tushare, yfinance, okx-market, akshare, mootdx, ccxt, eastmoney, sec-edgar, qveris | | Strategy | 19 | strategy-generate, cross-market-strategy, technical-basic, candlestick, ichimoku, elliott-wave, smc, multi-factor, ml-strategy | | Analysis | 21 | factor-research, macro-analysis, global-macro, valuation-model, earnings-forecast, credit-analysis, dividend-analysis | | Asset Class | 9 | options-strategy, options-advanced, convertible-bond, etf-analysis, asset-allocation, sector-rotation | | Crypto | 7 | perp-funding-basis, liquidation-heatmap, stablecoin-flow, defi-yield, onchain-analysis | | Flow | 8 | hk-connect-flow, us-etf-flow, edgar-sec-filings, financial-statement, adr-hshare | | Tool | 10 | backtest-diagnose, report-generate, pine-script, doc-reader, web-reader, vnpy-export, trade-journal | | Research | 2 | alpha-zoo, strategy-dev-manager | | Risk Analysis | 1 | ashare-pre-st-filter | Custom Data Source register your own historical OHLCV loader Need a market or vendor we don't ship a loader for? Add your own historical-bar loader and select it with source="". The steps edit package source, so run from a clone (pip install -e .). Write the loader — create agent/backtest/loaders/_loader.py with a class that satisfies DataLoaderProtocol (duck-typed, no base class needed) and is tagged with @register: import pandas as pd from backtest.loaders.registry import register @register class DataLoader: name = "mysource" # the value you pass as source= markets = {"us_equity"} # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex requires_auth = False def is_available(self) -> bool: return True # token present? network reachable? def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None): return {symbol: DataFrame indexed by trade_date, columns: open, high, low, close, volume} ... Register the module so @register fires — add "backtest.loaders._loader" to _loader_modules in agent/backtest/loaders/registry.py. Allow the name through config validation — add "mysource" to _VALID_SOURCES in agent/backtest/runner.py. (Optional) slot it into a market's FALLBACK_CHAINS in registry.py so source="auto" can reach it. Use it — source="mysource" in a backtest config, or via the CLI / agent. Real-time ticks / order-book depth are out of scope for loaders — the loader layer is point-in-time historical bars only. Live market data flows through the broker connectors instead: okx / binance / ccxt for crypto, futu / tiger for equities. Preset Trading Teams 30 swarm presets 🏢 30 ready-to-use agent teams ⚡ Pre-configured finance workflows 🎯 Investment, trading & risk management presets | Preset | Workflow | |--------|----------| | investment_committee | Bull/bear debate → risk review → PM final call | | global_equities_desk | A-share + HK/US + crypto researcher → global strategist | | crypto_trading_desk | Funding/basis + liquidation + flow → risk manager | | earnings_research_desk | Fundamental + revision + options → earnings strategist | | macro_rates_fx_desk | Rates + FX + commodity → macro PM | | quant_strategy_desk | Screening + factor research → backtest → risk audit | | technical_analysis_panel | Classic TA + Ichimoku + harmonic + Elliott + SMC → consensus | | risk_committee | Drawdown + tail risk + regime review → sign-off | | global_allocation_committee | A-shares + crypto + HK/US → cross-market allocation | Plus 20+ additional specialist presets — run vibe-trading --swarm-presets to explore all. Bring your own: drop preset YAMLs into ~/.vibe-trading/swarm/presets/ — they are listed alongside the bundled roster (same-name files override it, like user skills) and survive upgrades. Alpha Zoo 461 pre-built quant alphas across 5 families 🧬 461 cross-sectional alphas, lookahead-banned at the operator layer 📈 IC + IR + alive/reversed/dead categorisation in one CLI command 🔬 AST purity gate + 300-row lookahead sentinel test + pytest-socket network kill-switch 📦 Apache-2 attribution for Qlib; per-zoo LICENSE.md declaring formulas as mathematical content 🤝 Developer Certificate of Origin (DCO) sign-off workflow for community PRs | Zoo | Count | Source | License | |-----|-------|--------|---------| | qlib158 | 154 | Microsoft Qlib Alpha158 (Apache-2.0, commit-pinned) | Apache-2.0 | | alpha101 | 101 | Kakushadze (2015), "101 Formulaic Alphas", arXiv:1601.00991 | Formulas are mathematical content | | gtja191 | 191 | Guotai Junan (2014), "191 Short-period Trading Alpha Factors" | Formulas are mathematical content | | academic | 11 | Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew + Frazzini-Pedersen betting-against-beta (price-based proxies) | Public academic literature | | fundamental | 4 | PIT-safe SEC company facts — earnings yield, ROE, gross profitability, asset growth (filed-date anchored) | Public financial data | Run vibe-trading alpha list to browse, vibe-trading alpha show for formulas + source, vibe-trading alpha bench --zoo X --universe Y --period Z to score a whole zoo. 🎬 Demo https://github.com/user-attachments/assets/4e4dcb80-7358-4b9a-92f0-1e29612e6e86 https://github.com/user-attachments/assets/3754a414-c3ee-464f-b1e8-78e1a74fbd30 ☝️ Natural-language backtest & multi-agent swarm debate — Web UI + CLI 🚀 Quick Start One-line install (PyPI) pip install vibe-trading-ai Then run a first research task: vibe-trading init vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024 and summarize return and drawdown" Upgrading from an older version? 0.1.10 moved to LangChain 1.x. If imports break after pip install -U vibe-trading-ai over a pre-0.1.10 install (e.g. langgraph fails to import), recreate the venv or run pip instal

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

Skills for Real Engineers. Straight from my .agents directory.

Cangjie Skill 把书、长视频、播客里的方法论，蒸馏成可调用的 AI Skills License: MIT Method: RIA--TV++ Platform: OpenClaw Platform: Claude Code 读完、看完、听完之后，带走一套能调用的方法论。 为什么做这件事 最近有一个很火的 idea：把同事蒸馏成 skill。即便一个人离职了，他的经验、语气、工作方式都会被 AI 一定程度替代。nuwa-skill 就是做这件事的——创造"人类 skill"，比如马斯克 skill、巴菲特 skill。配套的 darwin-skill 负责让这些 skill 自动进化。 蒸馏人很有价值——nuwa-skill 已经证明了这一点。而蒸馏人系统性表达过的内容，则是另一个维度的补充：一本书、一场长访谈、一期播客、一个 B 站或 YouTube 长视频，都可能沉淀了作者花很长时间打磨出来的方法论。比起模仿一个人的表达方式，把他系统性输出的方法论拆出来、变成可以帮人解决实际问题的工具，同样是很有价值的事。 而且还有一个真实的痛点：你可能看了很多书、收藏了很多视频、听过很多播客，但就是运用不起来。尤其是各大平台每天都有大量干货长视频，时效性很强，内容又很长；它们往往不可能已经被 AI 训练过，也很难靠一次观看完整吸收。把这些内容蒸馏成 skill 之后，AI agent 可以帮你在真实场景中调用这些知识，而不是让它们躺在笔记、收藏夹或稍后再看列表里落灰。 所以 cangjie-skill 的目标很明确：蒸馏所有值得蒸馏的高价值内容。它不只适用于书，也适用于有字幕/转写文本的视频、播客、访谈、演讲、课程、长文和资料集。只要内容里存在可抽取、可验证、可迁移的方法论，就可以用 cangjie-skill 把它变成一套可独立调用、可组合使用、可压力测试的 AI skill 工具包。 如果要蒸馏视频内容，建议搭配 video-downloader skill 一起使用：先用它下载视频、提取字幕/音频转写和关键素材，再把得到的文本内容交给 cangjie-skill 做方法论抽取、skill 化和压力测试。 它解决了什么问题 看了很多书、视频、播客但用不起来——知识停留在"看过/听过/收藏过"层面，无法在真实决策中被调用 摘要、笔记、字幕整理只是压缩，不是结构化复用——读完/看完还是不知道"什么时候该用什么" 高价值内容里真正值得变成工具的内容只有一小部分——需要严格的筛选而不是照单全收 现有的阅读/观看/听课方法论都是给人看的，不是给 agent 用的——需要面向执行而非面向消费的蒸馏方法 它是怎么工作的 cangjie-skill 使用 RIA-TV++ 流水线，把书籍、视频转写、播客文字稿、访谈记录等原始文本变成一组结构化的 skill。整个过程分七个阶段： 整体内容理解（Adler 分析）——借鉴 Mortimer Adler 的分析阅读法，对整份内容做结构、解释、批判、应用四步拆解，产出 BOOK_OVERVIEW.md 并行提取——同时派 5 个专项提取器（框架、原则、案例、反例、术语），从原文中提取候选方法论单元 三重验证筛选——每个候选必须通过三项检验：原内容中至少有 2 处独立佐证（跨域）、能回答内容里未明说的新问题（预测力）、不是常识（独特性）。通过率通常只有 25-50% RIA++ 构造——将验证通过的内容按 R（原文引用）/ I（用自己的话重写）/ A1（书中案例）/ A2（未来触发场景）/ E（可执行步骤）/ B（边界与盲点）六个维度结构化 Zettelkasten 链接——找出 skill 之间的依赖、对比、组合关系，生成 INDEX.md 和引用图 压力测试——为每个 skill 设计包含诱饵题的测试用例（含跨 skill 混淆测试），未通过的回炉重做 交付——生成面向读者的 DIGEST.md 精华长文（不想读全书？看这篇就够），并把通过测试的 skill 安装到 Claude Code / Cursor 的 skills 目录，让它们真正可被调用 RIA-TV++ 这个名字拆开看： RIA：来自赵周《这样读书就够了》的便签拆书法（Reading / Interpretation / Appropriation） TV：Triple Verification，三重验证 ++：面向 agent 执行的扩展——E（Execution 可执行步骤）+ B（Boundary 边界） 效果示例 示例 1：从一本书/长视频到一套 skill 工具包 用户需求 "我想把一本书或一个 B 站/YouTube 长视频里的核心方法论抽成可复用的 AI skills，而不是只做摘要。" cangjie-skill 如何判断 先看源材料是否存在可重复调用的方法论单元 再区分哪些内容适合做独立 skill，哪些只适合做候选或背景 最后输出结构化 skill 仓库，而不是一篇总结文章 最终输出示例 输出将不是一个单文件摘要，而是一个多 skill 仓库：包含 BOOK_OVERVIEW.md 作为全局理解，INDEX.md 作为技能地图，DIGEST.md 作为面向读者的精华长文，GLOSSARY.md 作为术语词典，若干 */SKILL.md 作为独立模块，以及 test-prompts.json 用于验证触发场景。 示例 2：不是压缩，是结构化复用 用户需求 "我不希望这份内容只变成一个很长的说明文，我想要可以在 agent 里复用的技能包。" cangjie-skill 如何判断 判断目标不是内容总结，而是结构化复用 优先生成可触发、可组合、可测试的 skill 单元 对没有独立价值的内容进行淘汰，不强行保留 最终输出示例 系统会把内容拆成多个带触发条件、适用边界、使用方式和关联关系的 skills，而不是把整份内容压缩成一篇泛化总结。 已生成的 skill packs | 仓库 | 来源 | Skills 数 | |------|------|-----------| | buffett-letters-skill | 巴菲特致股东的信（1957-2023） | 20 | | cognitive-dividend-skill | 《认知红利》 | 15 | | duan-yongping-skill | 段永平投资问答录（商业逻辑+投资逻辑） | 15 | | viral-copywriting-skill | 《爆款文案》 | 14 | | copywriters-handbook-skill | 《文案创作完全手册》 | 12 | | contagious-skill | 《疯传》 | 15 | | influence-skill | 《影响力》 | 12 | | 1000-true-fans-skill | 《1000个铁粉》 | 13 | | system-prompt-skills | 165 个 AI 产品系统提示词 | 15 | | X-growth-skills | X（Twitter）起号、内容增长、算法、互动与变现实战资料集 | 15 | | poor-charlies-almanack-skill | 《穷查理宝典》 | 12 | | no-rules-rules-skill | 《不拘一格：网飞的自由与责任工作法》 | 10 | | huangdi-neijing-skill | 《黄帝内经》（素问+灵枢） | 22 | | first-principles-skill | 《第一性原理》 | 10 | | mao-selected-works-skill | 《毛泽东选集》第 1-5 卷 | 25 | | qbdx-hub/buffett-letters-skill | 沃伦·巴菲特 1957-2023 年致股东信 | 20 | | qbdx-hub/wo-yu-di-tan-skill | 史铁生《我与地坛》 | 6 | | qbdx-hub/mingchao-those-things-skill | 当年明月《明朝那些事儿》 | 7 | | qbdx-hub/sunzi-bingfa-skill | 《孙子兵法》 | 8 | | qbdx-hub/zhouyi-skill | 《周易》 | 8 | | qbdx-hub/high-math-vol1-ch1-skill | 高等数学上册第一章 | 8 | 视频蒸馏区 这些仓库来自长视频、课程或视频合集的字幕/转写文本，适合展示 cangjie-skill 对非书籍内容的方法论蒸馏能力。 | 仓库 | 来源 | Skills 数 | |------|------|-----------| | ai-for-everyone-skill | 吴恩达《AI for Everyone / 给所有人的 AI 入门课》视频课程 | 25 | | loop-engineering-skill | Loop Engineering 长视频合集 | 8 | 后续计划蒸馏更多高价值书籍。候选书单包括但不限于：君主论。 补充外部来源（经对方作者同意引入）： 来源仓库：ace3000chao/book2startup 书目包括：《精益创业》《孙子兵法》《庄子》《易经》 来源仓库：shenqistart/book2skill 书目包括：《缠论》《茶经》 仓库结构 cangjie-skill/ ├── README.md ← 你正在看的 ├── README.en.md ← English version ├── README.ja.md ← 日本語版 ├── LICENSE ← MIT ├── SKILL.md ← 元 skill 定义（cangjie-skill 的完整执行规范） ├── methodology/ ← RIA-TV++ 各阶段的方法论文档 ├── extractors/ ← 5 个并行提取器的 prompt 定义 └── templates/ ← SKILL.md / INDEX.md / BOOK_OVERVIEW.md 模板 生态 cangjie-skill 是一个更大的 skill 生态的一部分： nuwa-skill — 蒸馏人（思维方式、表达 DNA） cangjie-skill（本仓库）— 蒸馏书（方法论、框架、原则） darwin-skill — 进化任意 skill 三者咬合：nuwa 蒸馏人，cangjie 蒸馏书，darwin 让它们持续进化。 More Skills Buffett Letters Skill — 巴菲特 60+ 年致股东信的 20 个投资判断 skill Poor Charlie's Almanack Skill — 查理·芒格核心思维方法的 12 个决策与判断 skill No Rules Rules Skill — 网飞自由与责任文化的 10 个组织设计 skill Cognitive Dividend Skill — 《认知红利》思维升级的 15 个认知工具 skill Duan Yongping Skill — 段永平投资问答录的 15 个商业与投资 skill Viral Copywriting Skill — 《爆款文案》的 14 个销售型文案写作与诊断 skill Copywriters Handbook Skill — 《文案创作完全手册》的 12 个销售型文案、标题与卖点转化 skill Contagious Skill — 《疯传》的 15 个 STEPPS 传播策略与口碑诊断 skill Influence Skill — 《影响力》的 12 个说服心理、顺从机制与防御判断 skill 1000 True Fans Skill — 《1000个铁粉》的 13 个个人品牌、铁粉养成与信任变现 skill System Prompt Skills — 从 165 个 AI 产品系统提示词蒸馏出的 15 个 system prompt 设计 skill X Growth Skills — X 起号、内容、算法、互动、复盘与变现的 15 个运营 skill Huangdi Neijing Skill — 《黄帝内经》素问12+灵枢10共22个思维方法 skill First Principles Skill — 《第一性原理》的 10 个认知拆解、破界创新与组织刷新 skill Mao Selected Works Skill — 《毛泽东选集》第 1-5 卷的 25 个认知、战略、组织与执行方法 skill qbdx-hub Buffett Letters Skill — 沃伦·巴菲特 1957-2023 年致股东信的 20 个投资与资本配置 skill qbdx-hub Wo Yu Di Tan Skill — 《我与地坛》的 6 个限制、苦难、写作与自我安放 skill qbdx-hub Mingchao Those Things Skill — 《明朝那些事儿》的 7 个权力结构、制度失灵与历史表达 skill qbdx-hub Sunzi Bingfa Skill — 《孙子兵法》的 8 个战略判断、资源控制与行动选择 skill qbdx-hub Zhouyi Skill — 《周易》的 8 个处境诊断、时位判断与进退边界 skill qbdx-hub High Math Vol. 1 Chapter 1 Skill — 高等数学上册第一章的 8 个极限、无穷小与连续性学习 skill book2startup — 经作者同意引入的外部来源，包含《精益创业》《孙子兵法》《庄子》《易经》相关 skills book2skill — 经作者同意引入的外部来源，包含《缠论》《茶经》相关 AI-Agent skills 贡献者 感谢以下贡献者对 cangjie-skill 生态的补充： shenqistart — 贡献外部 book2skill 引用，并补充中英日 README 更新 qbdx-hub — 贡献 6 个 Cangjie 整书/章节蒸馏示例仓库，并补充中英日 README 引用 关于作者 袋鼠帝 kangarooking — AI 博主，独立开发者。AI Top 公众号「袋鼠帝 AI 客栈」主理人 火山引擎领航 KOL，百度千帆开发者大使，GLM 布道师，Trae 昆明第一任 Fellow | 平台 | 链接 | |------|------| | 𝕏 Twitter（袋鼠帝） | https://x.com/aikangarooking | | 小红书（袋鼠帝） | https://xhslink.com/m/5YejKvIDBbL | | 抖音（袋鼠帝） | https://v.douyin.com/hYpsjphuuKc | | 公众号 | 袋鼠帝 AI 客栈 | | 视频号 | AI 袋鼠帝 | 微信公众号「袋鼠帝 AI 客栈」二维码： 如果你也想把书、长视频、播客、课程里的方法论蒸馏成可调用的 Agent Skills，欢迎加入 cangjie-skill 企微交流群： ⭐ Star History 如果这个项目帮到了你，点个 Star 支持一下～ License MIT. See LICENSE.

OfficeCLI OfficeCLI is the world's first and the best Office suite designed for AI agents. Give any AI agent full control over Word, Excel, and PowerPoint — in one line of code. Open-source. Single binary. No Office installation. No dependencies. Works everywhere. OfficeCLI's built-in HTML rendering engine reproduces documents with high fidelity — and that's what gives AI eyes. It renders .docx / .xlsx / .pptx to HTML or PNG, closing the render → look → fix loop. GitHub Release License English | 中文 | 日本語 | 한국어 🌐 Website: officecli.ai | 💬 Community: Discord PPT creation process using OfficeCLI on AionUi PowerPoint Presentations — Word Documents — Excel Spreadsheets All documents above were created entirely by AI agents using OfficeCLI — no templates, no manual editing. For AI Agents — Get Started in One Line Paste this into your AI agent's chat — it will read the skill file and install everything automatically: curl -fsSL https://officecli.ai/SKILL.md That's it. The skill file teaches the agent how to install the binary and use all commands. For Humans Option A — GUI: Install AionUi — a desktop app that lets you create and edit Office documents through natural language, powered by OfficeCLI under the hood. Just describe what you want, and AionUi handles the rest. Option B — CLI: Download the binary for your platform from GitHub Releases, then run: officecli install This copies the binary to your PATH and installs the officecli skill into every AI coding agent it detects — Claude Code, Cursor, Windsurf, GitHub Copilot, and more. Your agent can immediately create, read, and edit Office documents on your behalf, no extra configuration needed. For Developers — See It Live in 30 Seconds 1. Install (macOS / Linux) — or: brew install officecli / npm install -g @officecli/officecli curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash Windows (PowerShell): irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex 2. Create a blank PowerPoint officecli create deck.pptx 3. Start live preview — opens http://localhost:26315 in your browser officecli watch deck.pptx 4. Open another terminal, add a slide — watch the browser update instantly officecli add deck.pptx / --type slide --prop title="Hello, World!" That's it. Every add, set, or remove command you run will refresh the preview in real time. Keep experimenting — the browser is your live feedback loop. Quick Start Create a presentation and add content officecli create deck.pptx officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E officecli add deck.pptx '/slide1]' --type shape \ --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \ --prop font=Arial --prop size=24 --prop color=FFFFFF View as outline officecli view deck.pptx outline → Slide 1: Q4 Report → Shape 1 [TextBox]: Revenue grew 25% View as HTML — opens a rendered preview in your browser, no server needed officecli view deck.pptx html Get structured JSON for any element officecli get deck.pptx '/slide[1]/shape[1]' --json Save and close — flushes the resident session to disk officecli close deck.pptx { "tag": "shape", "path": "/slide[1]/shape[1]", "attributes": { "name": "TextBox 1", "text": "Revenue grew 25%", "x": "720000", "y": "1800000" } } Why OfficeCLI? What used to take 50 lines of Python and 3 separate libraries: from pptx import Presentation from pptx.util import Inches, Pt prs = Presentation() slide = prs.slides.add_slide(prs.slide_layouts[0]) title = slide.shapes.title title.text = "Q4 Report" ... 45 more lines ... prs.save('deck.pptx') Now takes one command: officecli add deck.pptx / --type slide --prop title="Q4 Report" What OfficeCLI can do: Create documents from scratch -- blank or with content Read text, structure, styles, formulas -- in plain text or structured JSON Analyze formatting issues, style inconsistencies, and structural problems Modify any element -- text, fonts, colors, layout, formulas, charts, images Reorganize content -- add, remove, move, copy elements across documents | Format | Read | Modify | Create | |--------|------|--------|--------| | Word (.docx) | ✅ | ✅ | ✅ | | Excel (.xlsx) | ✅ | ✅ | ✅ | | PowerPoint (.pptx) | ✅ | ✅ | ✅ | Word — full [i18n & RTL support (per-script font slots, per-script BCP-47 lang tags lang.latin/ea/cs, complex-script bold/italic/size, direction=rtl cascading through paragraph/run/section/table/style/header/footer/docDefaults, rtlGutter + pgBorders shorthand, locale-aware page numbering for Hindi/Arabic/Thai/CJK; create --locale ar-SA auto-enables RTL), paragraphs (framePr, tabs shorthand, char-based indents), runs (underline.color, position half-pts), tables (virtual column ops add/remove/move/copyfrom, hMerge), styles, textbox / shape (textbox: rotation, textDirection eaVert/vert270, gradient, shadow, opacity), headers/footers, images (PNG/JPG/GIF/SVG), equations (LaTeX input), diagrams (mermaid → native editable shapes, or any mermaid type as a full-fidelity PNG), comments, footnotes, watermarks, bookmarks, TOC, charts, hyperlinks, sections, form fields, content controls (SDT), fields (22 zero-param types + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF), OLE objects, revisions / tracked changes (revision.type=ins\|del\|format\|moveFrom\|moveTo + revision.action=accept\|reject, per-target /revision@author=Alice] selector, tracked Find&Replace), page background color, [document properties Excel — cells (phonetic guide / furigana on add, Excel-UI --shift left\|up on remove / shift=right\|down on add), formulas (350+ built-in functions with auto-evaluation, spilling dynamic arrays with _xlfn. auto-prefix, financial / bond and statistical families, OFFSET/INDIRECT, defined-name formula bodies inlined at parse, formula-ref rewrite on row/col insert), sheets (visible/hidden/veryHidden, print margins, printTitleRows/Cols, RTL sheetView, cascade-aware sheet rename, empty-cell bloat filter on open), boolean and/or selectors (rowSalary>5000 and Region=EMEA]), [tables, sort (sheet / range, multi-key, sidecar-aware), conditional formatting, charts (including box-whisker, pareto with auto-sort + cumulative-%, log axis), pivot tables (multi-field, date grouping, showDataAs, sort, grandTotals, subtotals, compact/outline/tabular layout, repeat item labels, blank rows, calculated fields, persistent labelFilter / topN filters, cache CoW + cross-pivot sharing), slicers, named ranges, data validation, images (PNG/JPG/GIF/SVG with dual-representation fallback), sparklines, comments (RTL), autofilter, shapes, OLE objects, CSV/TSV import, $Sheet:A1 cell addressing PowerPoint — slides (header/footer/date/slidenum toggles, hidden), shapes (pattern fill, blur effect, hyperlink tooltip + slide-jump links, highlight color on runs, slideMaster/slideLayout typed add/set/remove, arrow alias, effective.X + effective.X.src), images (PNG/JPG/GIF/SVG, fill modes: stretch/contain/cover/tile, brightness/contrast/glow/shadow, rotation, link + tooltip), tables (built-in PowerPoint style catalogue, virtual /colC] get + swap/copyFrom, row/col Move/CopyFrom, fill/background alias), [charts (pieOfPie, barOfPie, per-attr axisLine/gridline setters, series add/remove with theme palette, anchor=x,y,w,h shorthand), animations (15 emphasis + 16 exit template-backed presets, multi-effect chains, motion-path presets, repeat/restart/autoReverse, chart animations + chartBuild), transitions (morph + p14 + 12 p15 PowerPoint 2013+ presets), 3D models (.glb) (combined rotation=ax,ay,az), slide zoom, equations (LaTeX input), diagrams (mermaid flowchart / sequence → native editable shapes, or any mermaid type as a full-fidelity PNG), themes, connectors (from/to accept a full /slideN]/shape[@name=Foo] path), [video/audio (loop, autoStart), groups (link + tooltip; Get/Query/Add/Remove all descend into groups), notes (RTL, lang), comments (RTL, legacy + modern p188 threaded round-trip), SmartArt (round-trip via add-part + raw-set), OLE objects, placeholders (add/set by phType) Use Cases For Developers: Automate report generation from databases or APIs Batch-process documents (bulk find/replace, style updates) Build document pipelines in CI/CD environments (generate docs from test results) Headless Office automation in Docker/containerized environments For AI Agents: Generate presentations from user prompts (see examples above) Extract structured data from documents to JSON Validate and check document quality before delivery For Teams: Clone document templates and populate with data Automated document validation in CI/CD pipelines Installation Ships as a single self-contained binary. The .NET runtime is embedded -- nothing to install, no runtime to manage. One-line install: macOS / Linux curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash Windows (PowerShell) irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex Or via a package manager: Homebrew (macOS / Linux) brew install officecli Scoop (Windows) scoop install officecli npm (all platforms — fetches the native binary for your platform) npm install -g @officecli/officecli Or download manually from GitHub Releases: | Platform | Binary | |----------|--------| | macOS Apple Silicon | officecli-mac-arm64 | | macOS Intel | officecli-mac-x64 | | Linux x64 | officecli-linux-x64 | | Linux ARM64 | officecli-linux-arm64 | | Windows x64 | officecli-win-x64.exe | | Windows ARM64 | officecli-win-arm64.exe | Verify installation: officecli --version Or self-install from a downloaded binary (or run bare officecli to auto-install): officecli install # explicit officecli # bare invocation also triggers install Updates are checked automatically in the background. Disable with officecli config autoUpdate false or skip per-invocation with OFFICECLI_SKIP_UPDATE=1. Configuration lives under ~/.officecli/config.json. Key Features Built-in Engines & Generation Primitives OfficeCLI is self-contained. The capabilities below ship inside the binary — no Office required. Rendering engine — high-fidelity, built-in OfficeCLI's keystone: a from-scratch, high-fidelity HTML rendering engine that lets an AI agent see the rendered document instead of guessing from the DOM. It covers shapes, charts (trendlines, error bars, waterfall, candlestick, sparklines), equations (OMML → LaTeX, rendered with KaTeX), 3D .glb models via Three.js, morph transitions, slide zoom, and shape effects. Per-page PNG screenshots are produced by piping the rendered HTML through a headless browser. Three modes: view html — standalone HTML file, assets inlined. Open in any browser. view screenshot — per-page PNG, ready for multimodal agents to read. watch — local HTTP server with auto-refreshing preview; every add / set / remove updates the browser instantly. Excel watch supports inline cell editing and drag-to-reposition charts. officecli view deck.pptx html -o /tmp/deck.html officecli view deck.pptx screenshot -o /tmp/deck.png # add --page 1-N for more slides officecli watch deck.pptx # http://localhost:26315 Without visualization, an agent generating slides is flying blind — it can read the DOM but can't tell if the title overflows or two shapes overlap. Because rendering is built into the binary, the render → look → fix loop works in CI, in Docker, on a server with no display — anywhere the binary runs. Formula & pivot engine 350+ built-in Excel functions evaluated automatically on write — write =SUM(A1:A2), get the cell, the value is already there. No round-trip through Office to recalc. Covers spilling dynamic arrays (FILTER / SORT / UNIQUE / SEQUENCE / LET / LAMBDA / MAP), VLOOKUP / XLOOKUP / INDEX / MATCH, financial & bond math (XIRR / PRICE / YIELD / DURATION / COUPNUM), statistical distributions, tests & regression (NORM.DIST / T.TEST / LINEST), and date & text functions. Plus native OOXML pivot tables from a source range with one command — multi-field rows/cols/filters, 10 aggregations, showDataAs modes, date grouping, calculated fields, top-N, layouts. Pivot cache + definition are written to OOXML, so Excel opens the file with the aggregation already populated: officecli add sales.xlsx '/Sheet1' --type pivottable \ --prop source='Data!A1:E10000' --prop rows='Region,Category' \ --prop cols=Quarter --prop values='Revenue:sum,Units:avg' \ --prop showDataAs=percentOfTotal Template merge — generate once, fill many merge replaces {{key}} placeholders in any .docx / .xlsx / .pptx with JSON data — across paragraphs, table cells, shapes, headers, footers, and chart titles. Agent designs the layout once (expensive); production code fills it N times (cheap, deterministic, zero token cost). Avoids the failure mode where an agent regenerates each report from scratch and produces N inconsistent layouts. officecli merge invoice-template.docx out-001.docx --data '{"client":"Acme","total":"$5,200"}' officecli merge q4-template.pptx q4-acme.pptx --data data.json Round-trip dump — learn from existing docs dump serializes any .docx, .pptx, or .xlsx — whole document or any subtree (a single paragraph, table, slide, worksheet, the styles part, numbering, theme, or settings) — into a replayable batch JSON; batch replays it. Given a sample the user wants to imitate, an agent reads the structured spec instead of raw OOXML XML, mutates, and replays. Bridges "I have an existing template" and "generate me 100 variations." officecli dump existing.docx -o blueprint.json # whole document officecli dump existing.docx /body/tbl1] -o table.json # any subtree officecli dump existing.xlsx /Sheet1 -o sheet.json # a single worksheet officecli batch new.docx --input blueprint.json Resident Mode & Batch For multi-step workflows, resident mode keeps the document in memory. Batch mode applies multiple operations in a single pass. Resident mode — near-zero latency via named pipes officecli open report.docx officecli set report.docx /body/p[1]/r[1] --prop bold=true officecli set report.docx /body/p[2]/r[1] --prop color=FF0000 officecli close report.docx Batch mode — multi-command execution (atomic by default: any failed item rolls back the whole batch) echo '[{"command":"set","path":"/slide[1]/shape[1]","props":{"text":"Hello"}}, {"command":"set","path":"/slide[1]/shape[2]","props":{"fill":"FF0000"}}]' \ | officecli batch deck.pptx --json Inline batch with --commands (no stdin needed) officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]' Keep whatever succeeds even if some items fail (pre-1.0.137 behavior) officecli batch deck.pptx --input updates.json --best-effort --json Stop at the first failing command instead of running the rest (still rolls back everything unless combined with --best-effort) officecli batch deck.pptx --input updates.json --stop-on-error --json Reading the file with another tool? Flush to disk first. officecli's own reads (get/query/view) always see your latest edits, so within officecli you never need to save. But a live resident defers the disk write, so before a non‑officecli program reads the file — python‑docx/openpyxl, Microsoft Word, a renderer, delivery/upload — flush it: > officecli set report.docx /body/p[1] --prop bold=true officecli save report.docx # flush, keep the resident warm (or close to flush + release) python my_reader.py report.docx # now sees the edit A live resident also auto‑flushes shortly after going idle (adaptive 2–10s, scaled to the document's measured save cost). For a pipeline where another program reads after every command, set OFFICECLI_RESIDENT_FLUSH=each — every mutation is on disk before the command returns, while the resident stays warm. Full flush model (each/auto/fixed/off, save / close, env tuning): [wiki → open / close. Three-Layer Architecture Start simple, go deep only when needed. | Layer | Purpose | Commands | |-------|---------|----------| | L1: Read | Semantic views of content | view (text, annotated, outline, stats, issues, html, svg, screenshot) | | L2: DOM | Structured element operations | get, query, set, add, remove, move, swap | | L3: Raw XML | Direct XPath access — universal fallback | raw, raw-set, add-part, validate | L1 — high-level views officecli view report.docx annotated officecli view budget.xlsx text --cols A,B,C --max-lines 50 L2 — element-level operations officecli query report.docx "run:contains(TODO)" officecli add budget.xlsx / --type sheet --prop name="Q2 Report" officecli move report.docx /body/p5] --to /body --index 1 L3 — raw XML when L2 isn't enough officecli raw deck.pptx '/slide[1]' officecli raw-set report.docx document \ --xpath "//w:p[1]" --action append \ --xml 'Injected text' AI Integration MCP Server Built-in [MCP server — register with one command: officecli mcp claude # Claude Code officecli mcp cursor # Cursor officecli mcp vscode # VS Code / Copilot officecli mcp lmstudio # LM Studio officecli mcp list # Check registration status Exposes all document operations as tools over JSON-RPC — no shell access needed. Direct CLI Integration Get OfficeCLI working with your AI agent in two steps: Install the binary -- one command (see Installation) Done. OfficeCLI automatically detects your AI tools (Claude Code, GitHub Copilot, Codex) by checking known config directories and installs its skill file. Your agent can immediately create, read, and modify any Office document. Manual setup (optional) If auto-install doesn't cover your setup, you can install the skill file manually: Feed SKILL.md to your agent directly: curl -fsSL https://officecli.ai/SKILL.md Install as a local skill for Claude Code: curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md Other agents: Include the contents of SKILL.md in your agent's system prompt or tool description. Why your agent will thrive on OfficeCLI Deterministic JSON output — every command supports --json with consistent schemas. No regex parsing, no scraping stdout. Path-based addressing — every element has a stable path (/slide1]/shape[2]). Agents navigate documents without understanding XML namespaces. (OfficeCLI syntax: 1-based indexing, element local names — not XPath.) Progressive complexity (L1 → L2 → L3) — agents start with read-only views, escalate to DOM ops, fall back to raw XML only when needed. Minimizes token usage. Self-healing workflow — validate, view issues, and the structured error codes (not_found, invalid_value, unsupported_property) return suggestions and valid ranges. Agents self-correct without human intervention. Built-in agent-friendly rendering engine — view html / view screenshot / watch emit HTML and PNG natively. No Office required. Agents can see their output and fix layout issues, even inside CI / Docker / headless environments. Built-in formula & pivot engine — 350+ Excel functions auto-evaluated on write (incl. spilling dynamic arrays, financial / bond and statistical families); native OOXML pivot tables from a source range with one command. Agents read computed values and shipped aggregations immediately, without round-tripping through Office. Template merge — agent designs the layout once, downstream code fills {{key}} placeholders N times. Avoids burning tokens regenerating every report from scratch. Round-trip dump — dump turns any .docx, .pptx, or .xlsx into replayable batch JSON. Agents learn from human-authored samples by reading a structured spec, not raw OOXML XML. Built-in help — when unsure about property names or value formats, the agent runs officecli set instead of guessing. Auto-install — OfficeCLI detects your AI tooling (Claude Code, Cursor, VS Code, …) and configures itself. No manual skill-file setup. Built-in Help Don't guess property names — drill into the help: officecli help pptx set # All settable elements and properties officecli help pptx set shape # Detail for one element type officecli help docx query # Selector reference: attributes, :contains, :has(), etc. Run officecli --help for the full overview. JSON Output Schemas All commands support --json. The general response shapes: Single element (get --json): {"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}} List of elements (query --json): [ {"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}}, {"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}} ] Errors return a non-zero exit code with a structured error object including error code, suggestion, and valid values when available: { "success": false, "error": { "error": "Slide 50 not found (total: 8)", "code": "not_found", "suggestion": "Valid Slide index range: 1-8" } } Error codes: not_found, invalid_value, unsupported_property, invalid_path, unsupported_type, missing_property, file_not_found, file_locked, invalid_selector. Property names are auto-corrected -- misspelling a property returns a suggestion with the closest match. Error Recovery -- Agents self-correct by inspecting available elements: Agent tries an invalid path officecli get report.docx /body/p[99] --json Returns: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}} Agent self-corrects by checking available elements officecli get report.docx /body --depth 1 --json Returns the list of available children, agent picks the right path Mutation confirmations (set, add, remove, move, create with --json): {"success": true, "path": "/slide[1]/shape[1]"} See officecli --help for full details on exit codes and error formats. Comparison | | OfficeCLI | Microsoft Office | LibreOffice | python-docx / openpyxl | |---|---|---|---|---| | Open source & free | ✓ (Apache 2.0) | ✗ (paid license) | ✓ | ✓ | | AI-native CLI + JSON | ✓ | ✗ | ✗ | ✗ | | Zero install (single binary) | ✓ | ✗ | ✗ | ✗ (Python + pip) | | Call from any language | ✓ (CLI) | ✗ (COM/Add-in) | ✗ (UNO API) | Python only | | Path-based element access | ✓ | ✗ | ✗ | ✗ | | Raw XML fallback | ✓ | ✗ | ✗ | Partial | | Built-in agent-friendly rendering engine | ✓ | ✗ | ✗ | ✗ | | Headless HTML/PNG output | ✓ | ✗ | Partial | ✗ | | Template merge ({{key}}) across formats | ✓ | ✗ | ✗ | ✗ | | Round-trip dump → batch JSON | ✓ | ✗ | ✗ | ✗ | | Live preview (auto-refresh on edit) | ✓ | ✗ | ✗ | ✗ | | Headless / CI | ✓ | ✗ | Partial | ✓ | | Cross-platform | ✓ | Windows/Mac | ✓ | ✓ | | Word + Excel + PowerPoint | ✓ | ✓ | ✓ | Separate libs | Command Reference | Command | Description | |---------|-------------| | [create | Create a blank .docx, .xlsx, or .pptx (type from extension) | | view | View content (modes: outline, text, annotated, stats (--page-count), issues, html, svg, screenshot, pdf (via exporter plugin), forms (via format-handler plugin)). docx supports --render auto\|native\|html. | | load_skill | Print embedded SKILL.md content for a specialized skill (no install) | | get | Get element and children (--depth N, --json) | | query | CSS-like query with boolean and/or, row-by-column-name (rowSalary>5000]), --find flag | | [set | Modify element properties; accepts selectors and Excel-native paths (parity with get/query), --find/--replace flags | | add | Add element (or clone with --from ) | | remove | Remove an element | | move | Move element (--to , --index N, --after , --before ) | | swap | Swap two elements | | validate | Validate against OpenXML schema | | view issues | Enumerate document issues (text overflow, missing alt text, formula errors, ...) | | batch | Multiple operations applied in a single pass (stdin, --input, or --commands; atomic by default — any failed item rolls back the whole batch — --best-effort to keep partial progress, --stop-on-error to abort early) | | dump | Serialize a .docx, .pptx, or .xlsx into a replayable batch JSON (round-trip via batch); accepts a subtree path | | refresh | Recalculate TOC page numbers / PAGE / cross-references (.docx; Word backend on Windows, headless-HTML fallback) | | plugins | List / inspect / lint installed plugins (extend to .doc, .hwpx, .pdf export via dump-reader / exporter / format-handler kinds) | | merge | Template merge — replace {{key}} placeholders with JSON data | | watch | Live HTML preview in browser with auto-refresh | | mcp | Start MCP server for AI tool integration | | raw | View raw XML of a document part | | raw-set | Modify raw XML via XPath | | add-part | Add a new document part (header, chart, etc.) | | open | Start resident mode (keep document in memory) | | close | Save and close resident mode | | install | Install binary + skills + MCP (all, claude, cursor, etc.) | | config | Get or set configuration | | help | Built-in help (e.g. officecli help pptx set shape) | End-to-End Workflow Example A typical self-healing agent workflow: create a presentation, populate it, verify, and fix issues -- all without human intervention. 1. Create officecli create report.pptx 2. Add content officecli add report.pptx / --type slide --prop title="Q4 Results" officecli add report.pptx '/slide1]' --type shape \ --prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28 officecli add report.pptx / --type slide --prop title="Details" officecli add report.pptx '/slide[2]' --type shape \ --prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm 3. Verify officecli view report.pptx outline officecli validate report.pptx 4. Fix any issues found officecli view report.pptx issues --json Address issues based on output, e.g.: officecli set report.pptx '/slide[1]/shape[1]' --prop font=Arial Units & Colors All dimension and color properties accept flexible input formats: | Type | Accepted formats | Examples | |------|-----------------|----------| | Dimensions | cm, in, pt, px, or raw EMU | 2cm, 1in, 72pt, 96px, 914400 | | Colors | Hex, named, RGB, theme | #FF0000, FF0000, red, rgb(255,0,0), accent1 | | Font sizes | Bare number or pt-suffixed | 14, 14pt, 10.5pt | | Spacing | pt, cm, in, or multiplier | 12pt, 0.5cm, 1.5x, 150% | Common Patterns Replace all Heading1 text in a Word doc officecli query report.docx "paragraph[style=Heading1]" --json | ... officecli set report.docx /body/p[1]/r[1] --prop text="New Title" Export all slide content as JSON officecli get deck.pptx / --depth 2 --json Bulk-update Excel cells officecli batch budget.xlsx --input updates.json --json Import CSV data into an Excel sheet officecli add budget.xlsx / --type sheet --prop name="Q1 Data" officecli import budget.xlsx "/Q1 Data" sales.csv --header Template merge for batch reports officecli merge invoice-template.docx invoice-001.docx --data '{"client":"Acme","total":"$5,200"}' Check document quality before delivery officecli validate report.docx && officecli view report.docx issues --json From Python or Node.js — install one of the thin resident-pipe SDKs (no per-call process spawn): Python — pip install officecli-sdk from officecli import Doc with Doc("deck.pptx") as d: d.add("/", type="slide", title="Q4 Report") print(d.get("/slide[1]")) // Node.js — npm install @officecli/sdk import { Doc } from "@officecli/sdk"; await using d = await Doc.open("deck.pptx"); await d.add("/", { type: "slide", title: "Q4 Report" }); console.log(await d.get("/slide[1]")); Both SDKs auto-provision the native CLI when missing (mirror-first, Windows-capable) and announce the install rather than doing it silently. Or wrap subprocess directly, one-shot: import json, subprocess def cli(*args): return json.loads(subprocess.check_output(["officecli", *args, "--json"], text=True)) cli("create", "deck.pptx") Documentation The [Wiki has detailed guides for every command, element type, and property: By format: Word | Excel | PowerPoint Workflows: End-to-end examples -- Word reports, Excel dashboards, PowerPoint decks, batch modifications, resident mode Runnable examples: examples/ -- copy-paste scripts (.sh/.py) for Word, Excel, and PowerPoint, with output files included Troubleshooting: Common errors and solutions AI agent guide: Decision tree for navigating the wiki Build from Source Requires .NET 10 SDK for compilation only. The output is a self-contained, native binary -- .NET is embedded in the binary and is not needed at runtime. ./build.sh License Apache License 2.0 Bug reports and contributions are welcome on GitHub Issues. If you find OfficeCLI useful, please give it a star on GitHub — it helps others discover the project. OfficeCLI.AI | GitHub

UI Skills UI Skills Skills for Design Engineers More on ui-skills.com Run npx ui-skills start to route your agent through the right UI skill set for the task. CLI npx ui-skills npx ui-skills start npx ui-skills categories npx ui-skills list --category motion npx ui-skills get baseline-ui License Licensed under the MIT license.

Lightweight coding agent that runs in your terminal