search_history
Search indexed shell history by keyword to retrieve matching commands with their timestamp, working directory, and exit code.
Instructions
Full-text search across indexed shell history. Returns matching commands with timestamp/cwd/exit code.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Keywords to search. Supports prefix match. | |
| limit | No |
Implementation Reference
- src/search.ts:24-35 (handler)Core handler function that executes the search_history tool logic. It builds an FTS (full-text search) query from the user input using escapeFts(), then queries the commands_fts table joined with commands, ordered by rank.
export function searchHistory(db: Database.Database, query: string, limit = 20): SearchRow[] { const fts = escapeFts(query); if (!fts) return []; const stmt = db.prepare(` SELECT c.id, c.cmd, c.ts, c.shell, c.cwd, c.exit_code, c.duration_ms, commands_fts.rank AS rank FROM commands_fts JOIN commands c ON c.id = commands_fts.rowid WHERE commands_fts MATCH ? ORDER BY rank LIMIT ? `); return stmt.all(fts, limit) as SearchRow[]; } - src/index.ts:43-53 (schema)Tool registration with inputSchema definition for search_history. Defines the 'query' (required string) and 'limit' (optional number, default 20) parameters.
{ name: "search_history", description: "Full-text search across indexed shell history. Returns matching commands with timestamp/cwd/exit code.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Keywords to search. Supports prefix match." }, limit: { type: "number", default: 20 }, }, required: ["query"], }, - src/index.ts:106-108 (registration)Handler dispatch in the CallToolRequestSchema callback that routes 'search_history' tool calls to the searchHistory function with Zod-parsed arguments.
if (name === "search_history") { const { query, limit } = z.object({ query: z.string(), limit: z.number().optional() }).parse(args); return { content: [{ type: "text", text: fmt(searchHistory(db, query, limit ?? 20)) }] }; - src/index.ts:12-14 (registration)Import of the searchHistory function from the search module.
import { searchHistory, recentInDir, - src/search.ts:14-22 (helper)Helper function that escapes user query tokens for SQLite FTS syntax (prefix matching with asterisk, quoted phrases).
function escapeFts(q: string): string { const tokens = q.split(/\s+/).filter(Boolean).map((t) => { const cleaned = t.replace(/["']/g, ""); if (!cleaned) return ""; if (/^[A-Za-z0-9_-]+$/.test(cleaned)) return cleaned + "*"; return `"${cleaned}"`; }).filter(Boolean); return tokens.join(" OR "); }