Do web research and data work with the agentbox CLI: web search, fetch and read pages, look up facts with source URLs, compare prices and products, extract prices/tables/dates/people from pages, get stock, index, FX and crypto quotes (incl. Taiwan .TW), check Polymarket odds, do arithmetic, get today's date, keep notes with sources, write a sourced Markdown report that passes a template check, and edit text files safely. Use when a task needs facts from the web, current numbers, citations, a report file, or a file edit. Do not use for small talk, opinions, or answers that need no source, and not for trivial math that does not go into an answer.
agentbox
agentbox is one command-line tool for research tasks. Run it with your shell/exec tool.
Every command prints exactly one JSON line.
When to use
- The task needs facts from the web, with source URLs.
- The task needs current numbers: prices, stock quotes, FX rates, Polymarket odds.
- The task asks for a report or answer file with citations.
- The task asks you to edit a text file.
Do not use it for small talk or for answers that need no source.
Read every result
Success: {"ok":true,"data":{...},"hint":"..."}
Failure: {"ok":false,"error":{"code":"...","message":"..."},"hint":"..."}
- Check
okfirst. - If
okis true, take facts only fromdata. Thehintnames a good next command. - If
okis false, readerror.codeand do whathintsays. - Exit code 2 means a bad flag. Run
agentbox search --help(use your command name) and fix the flag. - Retry an identical failing command at most once. Then change the keyword, flag or URL, or follow the hint.
Golden research workflow
agentbox now
agentbox note list --limit 5
agentbox note clear --apply # only if note list shows notes from an older task
agentbox search "EU AI Act general-purpose AI obligations" --max-results 5 --save 3
agentbox read doc:1 --grep obligations
agentbox read doc:1 --section 3
agentbox note add 'GPAI model obligations apply from 2 August 2025' --source https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai --tag findings
agentbox report build "EU AI Act: GPAI obligations" --template brief --out report.md --apply
agentbox file replace report.md --todo 1 --replace 'Providers of general-purpose AI models must meet transparency and copyright duties from 2 August 2025.' --apply
agentbox report check report.md --template brief
now: get today's date. Use it for "latest", "this week", and in the report. At the start of a new task,note list; if it shows notes from an older task,note clear --apply. Never clear notes in the middle of a task.search --save N: find pages and store the top N asdoc:1,doc:2, ...read doc:N --grep WORDor--section N: read only the part you need. Never dump a whole doc.note add: save each fact with its--sourceURL. Tag notes with a section word (summary,findings) oritem1,item2, ... for numbered reports (top-n, market-brief).extract/table: pull prices, dates, tables or people from docs, then sort or filter them.report build --template T --out FILE --apply: write a skeleton with exact headings, numbered<!-- TODO(N) -->placeholders, your notes and a Sources list.file replace FILE --todo N --replace TEXT --apply: fill each TODO.report check FILE --template T: readdata.passanddata.issues. Each issue has afixcommand. Run it (put your text where it says YOUR TEXT).- Repeat step 8 until
passis true. Then stop.
Command cheat-sheet
agentbox now --tz Asia/Taipei # date, time, weekday
agentbox calc "round(1299 * 0.85, 2)" # all arithmetic
agentbox search "best open source Notion alternative" --max-results 5 --save 2
agentbox search "Nvidia earnings" --news --time week # recent news
agentbox fetch https://example.com/pricing # one known URL -> doc:N + outline
agentbox read doc:2 --grep price # snippets around a word
agentbox read doc:2 --section 3 # one section from the outline
agentbox read doc:2 --offset 4000 # continue after truncated:true
agentbox note add 'Pro plan is $20/user/month' --source https://example.com/pricing --tag pricing
agentbox note list --tag pricing # notes and their sources
agentbox note clear --apply # only at the start of a new task
agentbox extract doc:1 doc:2 --kind prices --save-table
agentbox extract doc:3 --kind people --grep CEO
agentbox table show tbl:1
agentbox table query tbl:1 --where "value < 50" --sort value --select value,raw,url
agentbox table import prices.csv
agentbox table export tbl:1 --out prices.csv --apply
agentbox quote get NVDA 2330.TW ^TWII USDTWD=X
agentbox quote history 2330.TW --range 6mo
agentbox quote search "Taiwan Semiconductor"
agentbox market trending --limit 10
agentbox market search election --limit 10
agentbox market get balance-of-power-2026-midterms
agentbox market history 2026-balance-of-power-d-senate-d-house-949 --interval 1m
agentbox report templates
agentbox report template show top-n
agentbox report build "Top 3 Rust Web Frameworks" --template top-n --n 3 --out report.md --apply
agentbox report check report.md --template top-n --n 3
agentbox file read report.md --lines 1:40
agentbox file write answer.md --content '# Answer' --apply
agentbox file replace report.md --find "old text" --replace "new text" --apply
agentbox config get # which search backend/key is active (masked)
What to take from the output
search:data.results[]withtitle,url,snippet, anddocwhen saved.data.backendtells you the engine.fetch:data.docanddata.outline[](section,heading). Then useread.read:data.content. Ifdata.truncatedis true, continue with--offsetset todata.next_offset. With--grep:data.snippets[](section,text).note list:data.notes[](text,source,tag) anddata.sources[].extract:data.items[], each withcontextandurl(prices, dates, numbers also haveraw).data.tablewhen you used--save-table.table query:data.rows[]anddata.row_count.quote get:data.quotes[](price,change_pct,currency,time,market_state),data.errors[],data.note.market search/trending:data.events[](title,url,volume_24h,end_date,markets[]withquestion,odds,yes_pctorleaderandleader_pct).report check:data.pass,data.score,data.issues[](message,fix).file write/file replace:data.appliedanddata.diff.
Which reference to open
Open a reference file (relative to this skill folder) only when you need it:
| You need to... | Open |
|---|---|
| search better, read long pages, handle weak keyless results | references/research.md |
| get prices, tables, dates or people out of pages; filter or sort | references/data.md |
write a report file, pick a template, fix report check issues | references/reports.md |
| get stock/FX/crypto quotes or Polymarket odds | references/finance-markets.md |
edit files, write multi-line text, quote $ safely, use notes | references/files.md |
| do a known task type (stock briefing, executive lookup, pricing, Polymarket briefing, EU regulation, OSS alternatives, IT procurement, competitive or deep research, BYOK) | references/task-playbooks.md |
Hard rules
- Run
agentboxdirectly. Do not prefix it withpython3,bash -cor a guessed path. - Use agentbox instead of
curl,wget,python,jqorgrepon web pages. - Do not reimplement agentbox features in Python or shell scripts.
- Use
agentbox calcfor every number you compute (sums, percentages, averages, conversions). - Use
agentbox nowfor today's date. Never guess the date or year. - Cite only URLs that appeared in agentbox output in this task (search results, fetch, notes, quote, market). Never invent a URL.
- Do not paste raw page content into your answer. Summarize in your own words; quote at most one short sentence.
- Read with
--grepor--section. Do not read a whole doc page by page unless you must. - Writes need
--apply. Without it nothing is written; you only get a diff preview. Preview first when you change a file you did not create. - Put text in single quotes when it contains
$, a backtick or!:'Pro costs $20/month'. In double quotes the shell eats$20. - Do not type
\ninside quotes; it stays a literal backslash-n. For multi-line text use--replace -with a heredoc (seereferences/files.md). - Keep
--max-resultsat 3-8 and--limitsmall. Formarket searchandmarket trendinguse--limit 10or more. - Never ask for, print or set API keys. Do not run
agentbox config set. - If
data.backendisddgorbing, results are weaker: check that each result fits the question, add--site, and say so if the evidence is thin. - Do not re-run a command in a loop. If two different tries fail, report what failed and move on.
- Quotes may be about 15 minutes delayed. Polymarket percentages are market prices, not forecasts. Say so in the answer.
- Stop when
report checkreturnspass: true. Do not keep polishing.
Done criteria
- Every fact came from agentbox output in this task.
- Every claim has a source URL that agentbox returned.
- Every computed number came from
agentbox calc. - Time-sensitive data states the date from
agentbox now. - The requested file exists at the requested path (check with
agentbox file read report.md --lines 1:20). - If you wrote a report:
report checkreturnedpass: trueand no<!-- TODOor<!-- NOTESblocks remain. - The final answer is short, in your own words, and lists its sources.
Setup and safety (for the human operator)
- Install: the OpenClaw download installer fetches the v0.2.0 release archive from
GitHub Releases, checks its pinned sha256, and extracts it to
~/.openclaw/tools/agentbox/bin/. OpenClaw only finds binaries on PATH, so add that folder to PATH (Linux:export PATH="$HOME/.openclaw/tools/agentbox/bin:$PATH"; Windows: add%USERPROFILE%\.openclaw\tools\agentbox\binto the user Path), then start a new session. - macOS has no prebuilt binary. Build from source (Rust 1.85+):
cargo install --git https://github.com/alex-ht/agentbox --tag v0.2.0 --locked. - Network:
searchcalls api.tavily.com (only with a key), html.duckduckgo.com or bing.com;quotecalls finance.yahoo.com or stooq.com;marketcalls polymarket.com;fetch/extractread only the URLs the agent passes. - Keys are optional and set by the human (env
TAVILY_API_KEY, oragentbox config setrun by the human). agentbox never prints a key;config getshows it masked. - Local writes: state goes to
~/.agentbox(orAGENTBOX_HOME).fileedits andreport buildonly preview until--applyis given. No scripts run; this skill folder holds Markdown and one TOML sample.
Related skills
- Downloads
- 296All time
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v0.2.0
- License
- MIT-0
