Octen search skills for Claude Code and Codex: install, API key, and two doc-driven bug fixes

Install the skills

Commands below are from the official Octen-Team/octen-skills README (checked 2026-09-27):

# project-level, for a specific agent
npx skills add Octen-Team/octen-skills -a claude-code
npx skills add Octen-Team/octen-skills -a codex
npx skills add Octen-Team/octen-skills -a openclaw
npx skills add Octen-Team/octen-skills -a hermes-agent

# user-level (all projects)
npx skills add Octen-Team/octen-skills -g

# later
npx skills update

Start with the three core skills. octen-web-search is the router, octen-search handles focused and broad search, and octen-extract reads 1–20 known URLs. Image search, video search and octen-design are invite-only betas.

Set the API key

The skills need OCTEN_API_KEY. For Claude Code, put it in the env block of .claude/settings.local.json (project, keep it out of git) or ~/.claude/settings.json:

{
  "env": {
    "OCTEN_API_KEY": "your-key"
  }
}

For Codex, the README uses config.toml's shell-environment policy with a set mapping. Start a fresh session, confirm the agent can see the variable without printing it, then run one narrow lookup and check which tool was actually called. An install message alone doesn't prove the agent used Octen. No MCP server is required. The skills call the HTTP API directly, and a hosted MCP endpoint is optional. Our Claude skills guide covers how Claude Code discovers skills.

Search vs extract — the routing rule

• One API behaviour (where does Python raise the timeout?) → a focused search.
• You already have the docs URL → extract that page.
• A multi-angle decision (compare databases on hosting, licence and migration) → broad search. Broad search bills each generated sub-query, so one request can cost five.

The two fixes (and the caveat he's careful about)

• asyncio timeout. Catching TimeoutError inside asyncio.timeout() never fires. The context converts cancellation into TimeoutError as it exits, so the handler must wrap the whole block. The tests went from failing to 3/3, and an unrelated ValueError still propagates.
• SQLite foreign keys. PRAGMA foreign_keys = ON does nothing inside an open transaction. Moving it before BEGIN made orphan inserts raise IntegrityError.

He is explicit that the doc lookup was handed to Codex manually. These are real edits and real test runs, not an authenticated end-to-end benchmark. Octen's public demo also added misleading advice about deferring foreign keys and got a Cloudflare timeout question wrong, even with the right page in its results. The right page in the results doesn't guarantee the right answer. Make the agent quote the passage it used.

A prompt pattern worth copying

Inspect the project's dependency versions. Use Octen to find the official
documentation for that version, read the passage that determines this
behaviour, make the smallest change, and run the existing tests.
Show me the source passage and the diff. If the docs don't support a fix,
say what's missing instead of searching more broadly.

Cost

As quoted in the video (check the vendors' pricing pages before deciding): Octen is advertising a promotional $1 per 1,000 searches. Exa lists $7/1k for base search, Tavily basic works out to about $8/1k, and Parallel's fast and turbo modes start at $1/1k. Artificial Analysis's 22 September snapshot put Octen third on quality with the lowest latency. His advice: before switching, run three real tasks (a version-specific bug, a migration, and an unfamiliar API) and compare sources found, pass rate, number of searches and total cost.