@blogic-cz/agent-tools 0.5.7 → 0.7.0

package/README.md

@@ -27,6 +27,25 @@ These tools wrap each CLI with:
 bun add -d @blogic-cz/agent-tools
 ```
 
+### Skill installation
+
+Install per-tool skills for only the tools your project uses:
+
+```bash
+npx skills add blogic-cz/agent-tools --path skill/gh-tool
+npx skills add blogic-cz/agent-tools --path skill/db-tool
+npx skills add blogic-cz/agent-tools --path skill/k8s-tool
+npx skills add blogic-cz/agent-tools --path skill/az-tool
+npx skills add blogic-cz/agent-tools --path skill/logs-tool
+npx skills add blogic-cz/agent-tools --path skill/session-tool
+```
+
+Or install the all-in-one skill that covers every tool:
+
+```bash
+npx skills add blogic-cz/agent-tools --path skill/agent-tools
+```
+
 **Requirements:** [Bun](https://bun.sh/) >=1.0.0
 
 ### For agents reading this
@@ -41,8 +60,8 @@ Follow these steps to set up agent-tools in the consumer project.
   ```
 - **Non-JavaScript project** (no `package.json`): Skip installation — run tools directly with `bunx`:
   ```bash
-  bunx agent-tools-gh pr status
-  bunx agent-tools-k8s pods --env test
+  bunx gh-tool pr status
+  bunx k8s-tool pods --env test
   ```
 
 **Step 2 — Configure**
@@ -68,32 +87,54 @@ Set up the credential guard for the agent's platform:
 
 For each tool the user selected in Step 2:
 
-1. Run `bunx agent-tools-<tool> --help` to verify it works
+1. Run `bun <tool-name> --help` to verify it works (e.g. `bun gh-tool --help`)
 2. Summarize the key commands available
 3. Show the user what data they have access to based on their `agent-tools.json5` — e.g. which environments, clusters, namespaces, databases, or profiles are configured and reachable
 
 **Step 5 — Skill & Agent Docs**
 
-Tell the user to run the following command themselves — it's interactive and lets them choose which agents to install the skill for:
+Install **only the per-tool skills the project needs** (recommended), or the all-in-one skill:
 
 ```bash
-npx skills add blogic-cz/agent-tools
+# Per-tool skills (recommended) — install only what the project uses
+npx skills add blogic-cz/agent-tools --path skill/gh-tool
+npx skills add blogic-cz/agent-tools --path skill/db-tool
+npx skills add blogic-cz/agent-tools --path skill/k8s-tool
+npx skills add blogic-cz/agent-tools --path skill/az-tool
+npx skills add blogic-cz/agent-tools --path skill/logs-tool
+npx skills add blogic-cz/agent-tools --path skill/session-tool
+
+# All-in-one skill (alternative) — all tools in a single skill
+npx skills add blogic-cz/agent-tools --path skill/agent-tools
 ```
 
-**Do not run this command for the user** — it requires interactive selection.
+**Do not run these commands for the user** — they require interactive selection.
+
+Available per-tool skills:
+
+| Skill          | Install when project uses                  |
+| -------------- | ------------------------------------------ |
+| `gh-tool`      | GitHub PRs, issues, workflows, CI checks   |
+| `db-tool`      | SQL queries, schema introspection          |
+| `k8s-tool`     | Kubernetes pods, logs, deployments         |
+| `az-tool`      | Azure DevOps pipelines, builds             |
+| `logs-tool`    | Application log reading (local and remote) |
+| `session-tool` | OpenCode session history browsing          |
+| `agent-tools`  | All of the above in a single skill         |
 
 Then update the project's `AGENTS.md` and/or `CLAUDE.md`:
 
-1. Add an `agent-tools` row to the skills table (if one exists):
+1. Add rows to the skills table for each installed skill (if one exists):
    ```markdown
-   | Agent wrapper tools (`db-tool`, `k8s-tool`, `logs-tool`, `az-tool`, `gh` patterns) | `agent-tools` |
+   | GitHub PRs, issues, workflows | `gh-tool` |
+   | Database queries, schema | `db-tool` |
    ```
 2. Add or update the **Tooling** section:
 
    ```markdown
    ## Tooling
 
-   For tool wrappers and operational patterns, load `agent-tools`.
+   For tool wrappers and operational patterns, load the relevant tool skill (`gh-tool`, `db-tool`, etc.).
    ```
 
 **Step 6 — Custom Tool Scaffold**
@@ -146,34 +187,17 @@ bun run agent-tools/example-tool/index.ts ping
 3. Run tools:
 
 ```bash
-bunx agent-tools-gh pr status
-bunx agent-tools-k8s kubectl --env test --cmd "get pods"
-bunx agent-tools-logs list --env local
-bunx agent-tools-audit list --limit 20
+bun gh-tool pr status
+bun k8s-tool kubectl --env test --cmd "get pods"
+bun logs-tool list --env local
+bun audit-tool list --limit 20
 ```
 
 ```bash
-bunx agent-tools-gh pr review-triage   # interactive summary of PR feedback
-bunx agent-tools-k8s pods --env test   # list pods (structured command)
+bun gh-tool pr review-triage   # interactive summary of PR feedback
+bun k8s-tool pods --env test   # list pods (structured command)
 ```
 
-Optionally, add script aliases to your `package.json` for shorter invocation:
-
-```json
-{
-  "scripts": {
-    "gh-tool": "agent-tools-gh",
-    "audit-tool": "agent-tools-audit",
-    "k8s-tool": "agent-tools-k8s",
-    "db-tool": "agent-tools-db",
-    "logs-tool": "agent-tools-logs",
-    "session-tool": "agent-tools-session"
-  }
-}
-```
-
-Then run via `bun run k8s-tool -- pods --env test` instead of `bunx agent-tools-k8s pods --env test`.
-
 4. Hook up the credential guard in your agent config (Claude Code, OpenCode, etc.):
 
 ```typescript
@@ -184,19 +208,19 @@ export default { handleToolExecuteBefore };
 
 ## Tools
 
-| Binary                | Description                                                                                                      |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `agent-tools-gh`      | GitHub CLI wrapper — PR management, issues, workflows, composite commands (`review-triage`, `reply-and-resolve`) |
-| `agent-tools-audit`   | Audit trail browser — inspect recent tool invocations and purge old entries                                      |
-| `agent-tools-db`      | Database query tool — SQL execution, schema introspection                                                        |
-| `agent-tools-k8s`     | Kubernetes tool — kubectl wrapper + structured commands (`pods`, `logs`, `describe`, `exec`, `top`)              |
-| `agent-tools-az`      | Azure DevOps tool — pipelines, builds, repos                                                                     |
-| `agent-tools-logs`    | Application logs — read local and remote (k8s pod) logs                                                          |
-| `agent-tools-session` | OpenCode session browser — list, read, search sessions                                                           |
+| Binary         | Description                                                                                                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `gh-tool`      | GitHub CLI wrapper — PR management, issues, workflows, composite commands (`review-triage`, `reply-and-resolve`) |
+| `audit-tool`   | Audit trail browser — inspect recent tool invocations and purge old entries                                      |
+| `db-tool`      | Database query tool — SQL execution, schema introspection                                                        |
+| `k8s-tool`     | Kubernetes tool — kubectl wrapper + structured commands (`pods`, `logs`, `describe`, `exec`, `top`)              |
+| `az-tool`      | Azure DevOps tool — pipelines, builds, repos                                                                     |
+| `logs-tool`    | Application logs — read local and remote (k8s pod) logs                                                          |
+| `session-tool` | OpenCode session browser — list, read, search sessions                                                           |
 
-All tools support `--help` for full usage documentation.
+All tools support `--help` for full usage documentation. Legacy `agent-tools-*` binary names (e.g. `agent-tools-gh`) still work for backwards compatibility.
 
-`agent-tools-audit` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
+`audit-tool` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
 
 ## Audit Logging
 
@@ -212,19 +236,19 @@ Entries older than `retentionDays` (default: 90) are automatically purged on eac
 
 ```bash
 # Recent 20 entries (default)
-bunx agent-tools-audit list
+bun audit-tool list
 
 # Last 50 entries, JSON format
-bunx agent-tools-audit list --limit 50 --format json
+bun audit-tool list --limit 50 --format json
 
 # Filter by tool
-bunx agent-tools-audit list --tool gh
+bun audit-tool list --tool gh
 
 # Filter by project directory
-bunx agent-tools-audit list --project /Users/me/my-repo
+bun audit-tool list --project /Users/me/my-repo
 
 # Purge entries older than 30 days
-bunx agent-tools-audit purge --days 30
+bun audit-tool purge --days 30
 ```
 
 ### Audit Configuration
@@ -293,8 +317,8 @@ Each tool section supports multiple named profiles. Select with `--profile <name
 ```
 
 ```bash
-bunx agent-tools-az cmd --cmd "pipelines list"                    # uses "default" profile
-bunx agent-tools-az cmd --cmd "pipelines list" --profile legacy   # uses "legacy" profile
+bun az-tool cmd --cmd "pipelines list"                    # uses "default" profile
+bun az-tool cmd --cmd "pipelines list" --profile legacy   # uses "legacy" profile
 ```
 
 **Profile resolution:** `--profile` flag > auto-select (single profile) > `"default"` key > error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.5.7",
+  "version": "0.7.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",
@@ -25,7 +25,14 @@
     "agent-tools-gh": "./src/gh-tool/index.ts",
     "agent-tools-k8s": "./src/k8s-tool/index.ts",
     "agent-tools-logs": "./src/logs-tool/index.ts",
-    "agent-tools-session": "./src/session-tool/index.ts"
+    "agent-tools-session": "./src/session-tool/index.ts",
+    "audit-tool": "./src/audit-tool/index.ts",
+    "az-tool": "./src/az-tool/index.ts",
+    "db-tool": "./src/db-tool/index.ts",
+    "gh-tool": "./src/gh-tool/index.ts",
+    "k8s-tool": "./src/k8s-tool/index.ts",
+    "logs-tool": "./src/logs-tool/index.ts",
+    "session-tool": "./src/session-tool/index.ts"
   },
   "files": [
     "src/",

package/src/gh-tool/index.ts

@@ -47,6 +47,7 @@ import {
 import { repoInfoCommand, repoListCommand, repoSearchCodeCommand } from "./repo";
 import { GitHubService } from "./service";
 import {
+  workflowAnnotationsCommand,
   workflowCancelCommand,
   workflowJobLogsCommand,
   workflowJobsCommand,
@@ -104,7 +105,7 @@ const repoCommand = Command.make("repo", {}).pipe(
 
 const workflowCommand = Command.make("workflow", {}).pipe(
   Command.withDescription(
-    "GitHub Actions workflow operations (list runs, view, jobs, logs, job-logs, rerun, cancel, watch)",
+    "GitHub Actions workflow operations (list runs, view, jobs, logs, job-logs, annotations, rerun, cancel, watch)",
   ),
   Command.withSubcommands([
     workflowListCommand,
@@ -112,6 +113,7 @@ const workflowCommand = Command.make("workflow", {}).pipe(
     workflowJobsCommand,
     workflowLogsCommand,
     workflowJobLogsCommand,
+    workflowAnnotationsCommand,
     workflowRerunCommand,
     workflowCancelCommand,
     workflowWatchCommand,
@@ -152,10 +154,11 @@ WORKFLOW FOR AI AGENTS:
   12. Use 'workflow view --run N' to inspect a specific run with jobs/steps
   13. Use 'workflow logs --run N' to get logs (failed jobs by default)
   14. Use 'workflow job-logs --run N --job "build-web-app"' to get clean parsed logs for a specific job
-  15. Use 'workflow watch --run N' to watch until completion
-  16. Use 'release status' to inspect latest release + repository context
-  17. Use 'release create --tag vX.Y.Z --generate-notes' to publish a release
-  18. Use 'release edit/view/list/delete' to maintain existing releases`,
+  15. Use 'workflow annotations --run N' to list CI annotations (errors, warnings, notices)
+  16. Use 'workflow watch --run N' to watch until completion
+  17. Use 'release status' to inspect latest release + repository context
+  18. Use 'release create --tag vX.Y.Z --generate-notes' to publish a release
+  19. Use 'release edit/view/list/delete' to maintain existing releases`,
   ),
   Command.withSubcommands([prCommand, issueCommand, repoCommand, workflowCommand, releaseCommand]),
 );

package/src/gh-tool/types.ts

@@ -96,3 +96,21 @@ export type PRStatusNone = {
 };
 
 export type PRStatusResult = PRStatusSingle | PRStatusMultiple | PRStatusNone;
+
+export type CheckRunAnnotation = {
+  path: string;
+  start_line: number;
+  end_line: number;
+  start_column: number | null;
+  end_column: number | null;
+  annotation_level: "notice" | "warning" | "failure";
+  title: string | null;
+  message: string;
+  raw_details: string | null;
+};
+
+export type JobAnnotations = {
+  jobId: number;
+  jobName: string;
+  annotations: CheckRunAnnotation[];
+};

package/src/gh-tool/workflow.ts

@@ -4,6 +4,7 @@ import { Console, Effect, Option } from "effect";
 import { formatOption, logFormatted } from "#shared";
 import { GitHubCommandError, GitHubNotFoundError } from "./errors";
 import { GitHubService } from "./service";
+import type { CheckRunAnnotation, JobAnnotations } from "./types";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -235,6 +236,69 @@ const watchRun = Effect.fn("workflow.watchRun")(function* (runId: number, repo:
   };
 });
 
+const fetchAnnotations = Effect.fn("workflow.fetchAnnotations")(function* (opts: {
+  runId: number;
+  job: string | null;
+  repo: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  let owner: string;
+  let repoName: string;
+  if (opts.repo !== null) {
+    const parts = opts.repo.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      return yield* new GitHubCommandError({
+        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "blogic-cz/agent-tools").`,
+        command: "workflow annotations",
+        exitCode: 1,
+        stderr: "",
+      });
+    }
+    owner = parts[0];
+    repoName = parts[1];
+  } else {
+    const info = yield* gh.getRepoInfo();
+    owner = info.owner;
+    repoName = info.name;
+  }
+
+  const jobs = yield* listJobs(opts.runId, opts.repo);
+
+  let targetJobs = jobs;
+  if (opts.job !== null) {
+    const jobId = yield* resolveJobId(opts.runId, opts.job, opts.repo);
+    targetJobs = jobs.filter((j) => j.databaseId === jobId);
+  }
+
+  const results: JobAnnotations[] = [];
+  for (const job of targetJobs) {
+    const annotations = yield* gh
+      .runGhJson<CheckRunAnnotation[]>([
+        "api",
+        `repos/${owner}/${repoName}/check-runs/${job.databaseId}/annotations`,
+        "--paginate",
+      ])
+      .pipe(
+        Effect.catchTag("GitHubCommandError", () => Effect.succeed([] as CheckRunAnnotation[])),
+      );
+
+    if (annotations.length > 0) {
+      results.push({
+        jobId: job.databaseId,
+        jobName: job.name,
+        annotations,
+      });
+    }
+  }
+
+  return {
+    runId: opts.runId,
+    totalAnnotations: results.reduce((sum, r) => sum + r.annotations.length, 0),
+    jobs: results,
+  };
+});
+
 // ---------------------------------------------------------------------------
 // Log parsing utilities (pure functions)
 // ---------------------------------------------------------------------------
@@ -605,3 +669,29 @@ export const workflowJobLogsCommand = Command.make(
     "Fetch parsed, clean logs for a specific job in a workflow run. Resolves job name to ID, strips timestamps/ANSI, groups by step.",
   ),
 );
+
+export const workflowAnnotationsCommand = Command.make(
+  "annotations",
+  {
+    format: formatOption,
+    job: Flag.string("job").pipe(
+      Flag.withDescription("Filter to a specific job name (exact or partial match)"),
+      Flag.optional,
+    ),
+    repo: repoOption,
+    run: Flag.integer("run").pipe(Flag.withDescription("Workflow run ID")),
+  },
+  ({ format, job, repo, run }) =>
+    Effect.gen(function* () {
+      const result = yield* fetchAnnotations({
+        runId: run,
+        job: Option.getOrNull(job),
+        repo: Option.getOrNull(repo),
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "List annotations (errors, warnings, notices) from check runs in a workflow run. Shows problem matcher output, test failures, and other CI annotations.",
+  ),
+);

package/src/session-tool/claude-code.ts

@@ -0,0 +1,272 @@
+import { Effect } from "effect";
+import { readdir } from "node:fs/promises";
+
+import type { MessageSummary } from "./types";
+
+import { SessionReadError, SessionStorageNotFoundError, type SessionError } from "./errors";
+
+export const encodeProjectPath = (dir: string): string => dir.replaceAll("/", "-");
+
+export type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | { type: "tool_use"; id: string; name: string; input: unknown }
+  | { type: "tool_result"; tool_use_id: string; content: string };
+
+export type ClaudeCodeRecord =
+  | { type: "summary"; summary: string }
+  | {
+      type: "user";
+      timestamp: string;
+      uuid: string;
+      message: { role: "user"; content: string | ReadonlyArray<ContentBlock> };
+    }
+  | {
+      type: "assistant";
+      timestamp: string;
+      uuid: string;
+      message: { role: "assistant"; content: ReadonlyArray<ContentBlock> };
+    };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isContentBlock = (value: unknown): value is ContentBlock => {
+  if (!isRecord(value) || typeof value.type !== "string") {
+    return false;
+  }
+
+  switch (value.type) {
+    case "text":
+      return typeof value.text === "string";
+    case "thinking":
+      return typeof value.thinking === "string";
+    case "tool_use":
+      return typeof value.id === "string" && typeof value.name === "string";
+    case "tool_result":
+      return typeof value.tool_use_id === "string" && typeof value.content === "string";
+    default:
+      return false;
+  }
+};
+
+const isUserRecord = (
+  value: Record<string, unknown>,
+): value is Extract<ClaudeCodeRecord, { type: "user" }> => {
+  if (
+    value.type !== "user" ||
+    typeof value.timestamp !== "string" ||
+    typeof value.uuid !== "string"
+  ) {
+    return false;
+  }
+
+  if (!isRecord(value.message) || value.message.role !== "user") {
+    return false;
+  }
+
+  if (typeof value.message.content === "string") {
+    return true;
+  }
+
+  return Array.isArray(value.message.content) && value.message.content.every(isContentBlock);
+};
+
+const isAssistantRecord = (
+  value: Record<string, unknown>,
+): value is Extract<ClaudeCodeRecord, { type: "assistant" }> => {
+  if (
+    value.type !== "assistant" ||
+    typeof value.timestamp !== "string" ||
+    typeof value.uuid !== "string" ||
+    !isRecord(value.message) ||
+    value.message.role !== "assistant"
+  ) {
+    return false;
+  }
+
+  return Array.isArray(value.message.content) && value.message.content.every(isContentBlock);
+};
+
+export const parseJsonlLine = (line: string): ClaudeCodeRecord | null => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  if (!isRecord(parsed) || typeof parsed.type !== "string") {
+    return null;
+  }
+
+  if (parsed.type === "summary" && typeof parsed.summary === "string") {
+    return {
+      type: "summary",
+      summary: parsed.summary,
+    };
+  }
+
+  if (isUserRecord(parsed)) {
+    return parsed;
+  }
+
+  if (isAssistantRecord(parsed)) {
+    return parsed;
+  }
+
+  if (
+    parsed.type === "system" ||
+    parsed.type === "progress" ||
+    parsed.type === "file-history-snapshot" ||
+    parsed.type === "queue-operation"
+  ) {
+    return null;
+  }
+
+  return null;
+};
+
+export const extractTextFromContent = (content: string | ReadonlyArray<ContentBlock>): string => {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  return content
+    .filter((block): block is Extract<ContentBlock, { type: "text" }> => block.type === "text")
+    .map((block) => block.text)
+    .join("\n");
+};
+
+export const extractSessionTitle = (records: ReadonlyArray<ClaudeCodeRecord>): string => {
+  const summaryRecord = records.find((record) => record.type === "summary");
+  if (summaryRecord !== undefined) {
+    return summaryRecord.summary;
+  }
+
+  const firstUserRecord = records.find((record) => record.type === "user");
+  if (firstUserRecord !== undefined) {
+    return extractTextFromContent(firstUserRecord.message.content).slice(0, 100);
+  }
+
+  return "Untitled session";
+};
+
+export const getClaudeCodeSessions = (
+  basePath: string,
+  projectDir: string | null,
+): Effect.Effect<string[], SessionError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const targetProjectDir = projectDir === null ? null : encodeProjectPath(projectDir);
+      const projectEntries = await readdir(basePath, { withFileTypes: true });
+
+      const sessionFiles: string[] = [];
+
+      for (const entry of projectEntries) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+
+        if (targetProjectDir !== null && entry.name !== targetProjectDir) {
+          continue;
+        }
+
+        const projectPath = `${basePath}/${entry.name}`;
+        let files: string[];
+        try {
+          // eslint-disable-next-line eslint/no-await-in-loop -- directory scan must finish before filtering file list
+          files = await readdir(projectPath);
+        } catch {
+          continue;
+        }
+
+        for (const fileName of files) {
+          if (!fileName.endsWith(".jsonl") || fileName.startsWith("agent-")) {
+            continue;
+          }
+
+          sessionFiles.push(`${projectPath}/${fileName}`);
+        }
+      }
+
+      return sessionFiles;
+    },
+    catch: (error) =>
+      new SessionStorageNotFoundError({
+        message: error instanceof Error ? error.message : "Claude Code storage directory not found",
+        path: basePath,
+      }),
+  });
+
+const getFileNameWithoutExtension = (filePath: string): string => {
+  const fileName = filePath.split("/").pop();
+  if (fileName === undefined) {
+    return "";
+  }
+
+  if (!fileName.endsWith(".jsonl")) {
+    return fileName;
+  }
+
+  return fileName.slice(0, -".jsonl".length);
+};
+
+export const readClaudeCodeMessages = (
+  sessionFiles: string[],
+): Effect.Effect<MessageSummary[], SessionError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const summaries: MessageSummary[] = [];
+
+      for (const sessionFile of sessionFiles) {
+        let fileContent: string;
+        try {
+          // eslint-disable-next-line eslint/no-await-in-loop -- sequential file read keeps memory bounded
+          fileContent = await Bun.file(sessionFile).text();
+        } catch {
+          continue;
+        }
+
+        const records = fileContent
+          .split(/\r?\n/u)
+          .map((line) => line.trim())
+          .filter((line) => line.length > 0)
+          .map(parseJsonlLine)
+          .filter((record): record is ClaudeCodeRecord => record !== null);
+
+        const title = extractSessionTitle(records);
+        const sessionID = getFileNameWithoutExtension(sessionFile);
+
+        for (const record of records) {
+          if (record.type !== "user" && record.type !== "assistant") {
+            continue;
+          }
+
+          const createdTimestamp = new Date(record.timestamp).getTime();
+          summaries.push({
+            sessionID,
+            id: record.uuid,
+            title,
+            body: extractTextFromContent(record.message.content),
+            created: Number.isFinite(createdTimestamp) ? createdTimestamp : 0,
+            role: record.type,
+            source: "claude-code",
+          });
+        }
+      }
+
+      return (
+        summaries as MessageSummary[] & {
+          toSorted(
+            compareFn: (left: MessageSummary, right: MessageSummary) => number,
+          ): MessageSummary[];
+        }
+      ).toSorted((left, right) => right.created - left.created);
+    },
+    catch: (error) =>
+      new SessionReadError({
+        message: error instanceof Error ? error.message : "Failed to read Claude Code sessions",
+        source: "claude-code",
+      }),
+  });

package/src/session-tool/config.ts

@@ -1,4 +1,5 @@
 import { Effect, Layer, ServiceMap } from "effect";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -42,6 +43,7 @@ export class ResolvedPaths extends ServiceMap.Service<
   {
     readonly messagesPath: string;
     readonly sessionsPath: string;
+    readonly claudeCodePath: string | null;
   }
 >()("@agent-tools/ResolvedPaths") {}
 
@@ -50,6 +52,8 @@ export const ResolvedPathsLayer = Layer.effect(
   Effect.gen(function* () {
     const messagesPath = yield* resolveMessagesPath;
     const sessionsPath = yield* resolveSessionsPath;
-    return { messagesPath, sessionsPath };
+    const claudeCodeBasePath = join(homedir(), ".claude/projects");
+    const claudeCodePath = existsSync(claudeCodeBasePath) ? claudeCodeBasePath : null;
+    return { messagesPath, sessionsPath, claudeCodePath };
   }),
 );

package/src/session-tool/index.ts

@@ -11,7 +11,7 @@ import { Argument, Command, Flag } from "effect/unstable/cli";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Console, Effect, Layer, Result } from "effect";
 
-import type { MessageSummary, SessionResult } from "./types";
+import type { MessageSummary, SessionResult, SessionSource } from "./types";
 
 import { formatOption, formatOutput, VERSION } from "#shared";
 import { AuditServiceLayer, withAudit } from "#shared/audit";
@@ -21,6 +21,16 @@ import { formatDate, SessionService, SessionServiceLayer, truncate } from "./ser
 
 const AppLayer = SessionServiceLayer.pipe(Layer.provideMerge(ResolvedPathsLayer));
 
+const sourceOption = Flag.string("source").pipe(
+  Flag.withDescription("Filter by source: all, opencode, claude-code"),
+  Flag.withDefault("all"),
+);
+
+const filterBySource = (summaries: MessageSummary[], source: string): MessageSummary[] => {
+  if (source === "all") return summaries;
+  return summaries.filter((s) => s.source === (source as SessionSource));
+};
+
 const buildScopeLabel = (searchAll: boolean, currentDir: string) => {
   if (searchAll) {
     return "all projects";
@@ -39,9 +49,14 @@ const mapSummary = (summary: MessageSummary) => {
       title: summary.title,
       body: truncate(summary.body, 500),
       created: formatDate(summary.created),
-      messagePath: `${paths.messagesPath}/${summary.sessionID}/${summary.id}.json`,
+      ...(summary.source === "opencode"
+        ? {
+            messagePath: `${paths.messagesPath}/${summary.sessionID}/${summary.id}.json`,
+            sessionPath: `${paths.messagesPath}/${summary.sessionID}`,
+          }
+        : {}),
       role: summary.role,
-      sessionPath: `${paths.messagesPath}/${summary.sessionID}`,
+      source: summary.source,
     };
   });
 };
@@ -58,8 +73,9 @@ const listCommand = Command.make(
       Flag.withDescription("Limit result count"),
       Flag.withDefault(10),
     ),
+    source: sourceOption,
   },
-  ({ all, format, limit }) =>
+  ({ all, format, limit, source }) =>
     Effect.gen(function* () {
       const sessionService = yield* SessionService;
       const startTime = Date.now();
@@ -83,11 +99,13 @@ const listCommand = Command.make(
           } satisfies SessionResult;
         }
 
-        const summaries = yield* sessionService.getMessageSummaries(sessionFilter);
+        const allSummaries = yield* sessionService.getMessageSummaries(sessionFilter);
+        const summaries = filterBySource(allSummaries, source);
         const results = summaries.slice(0, limit).map((summary) => ({
           created: formatDate(summary.created),
           sessionID: summary.sessionID,
           title: summary.title,
+          source: summary.source,
         }));
 
         return {
@@ -132,8 +150,9 @@ const searchCommand = Command.make(
       Flag.withDescription("Limit result count"),
       Flag.withDefault(10),
     ),
+    source: sourceOption,
   },
-  ({ all, format, limit, query }) =>
+  ({ all, format, limit, query, source }) =>
     Effect.gen(function* () {
       const sessionService = yield* SessionService;
       const startTime = Date.now();
@@ -158,7 +177,8 @@ const searchCommand = Command.make(
           } satisfies SessionResult;
         }
 
-        const summaries = yield* sessionService.getMessageSummaries(sessionFilter);
+        const allSummaries = yield* sessionService.getMessageSummaries(sessionFilter);
+        const summaries = filterBySource(allSummaries, source);
         const matched = sessionService.searchSummaries(summaries, query);
         const mappedResults = yield* Effect.all(matched.slice(0, limit).map(mapSummary));
 
@@ -196,15 +216,16 @@ const searchCommand = Command.make(
 
       yield* Console.log(formatOutput(output, format));
     }),
-).pipe(Command.withDescription("Search OpenCode message history"));
+).pipe(Command.withDescription("Search message history"));
 
 const readCommand = Command.make(
   "read",
   {
     session: Flag.string("session").pipe(Flag.withDescription("Session ID to read")),
     format: formatOption,
+    source: sourceOption,
   },
-  ({ format, session }) =>
+  ({ format, session, source }) =>
     Effect.gen(function* () {
       const sessionService = yield* SessionService;
       const startTime = Date.now();
@@ -226,14 +247,19 @@ const readCommand = Command.make(
             executionTimeMs: Date.now() - startTime,
           } satisfies SessionResult),
         onSuccess: (summaries) => {
-          const sessionResults = summaries.filter((summary) => summary.sessionID === session);
+          const filtered = filterBySource(summaries, source);
+          const sessionResults = filtered.filter((summary) => summary.sessionID === session);
           return Effect.all(sessionResults.map(mapSummary)).pipe(
             Effect.map(
               (mapped) =>
                 ({
                   success: true,
                   data: {
-                    files: mapped.map((message) => message.messagePath),
+                    files: mapped
+                      .map((message) =>
+                        "messagePath" in message ? (message.messagePath as string) : null,
+                      )
+                      .filter((filePath): filePath is string => filePath !== null),
                     messages: mapped,
                     session,
                   },

package/src/session-tool/service.ts

@@ -3,6 +3,7 @@ import { readdir } from "node:fs/promises";
 
 import type { MessageSummary, SessionInfo } from "./types";
 
+import { getClaudeCodeSessions, readClaudeCodeMessages } from "./claude-code";
 import { ResolvedPaths } from "./config";
 import { SessionReadError, SessionStorageNotFoundError, type SessionError } from "./errors";
 
@@ -37,6 +38,37 @@ export const truncate = (value: string, maxLen: number): string => {
 
 type FileEntry = { filePath: string; content: string };
 
+type SourceFilter = "both" | "opencode" | "claude-code";
+
+const UUID_SESSION_ID_REGEX =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/u;
+
+const getSessionIdFromClaudeFile = (filePath: string): string => {
+  const fileName = filePath.split("/").pop() ?? "";
+  return fileName.endsWith(".jsonl") ? fileName.slice(0, -".jsonl".length) : fileName;
+};
+
+const detectSourceFilter = (filterSessions: Set<string> | null): SourceFilter => {
+  if (filterSessions === null || filterSessions.size !== 1) {
+    return "both";
+  }
+
+  const sessionId = filterSessions.values().next().value;
+  if (typeof sessionId !== "string") {
+    return "both";
+  }
+
+  if (sessionId.startsWith("ses_")) {
+    return "opencode";
+  }
+
+  if (UUID_SESSION_ID_REGEX.test(sessionId)) {
+    return "claude-code";
+  }
+
+  return "both";
+};
+
 /**
  * Reads JSON files from a two-level directory (parent/sub/*.json) using Bun.file().
  * Required for ~100k OpenCode message files where shell-per-file would timeout.
@@ -131,16 +163,42 @@ export class SessionService extends ServiceMap.Service<
         getSessionsForProject: Effect.fn("SessionService.getSessionsForProject")(function* (
           projectDir: string | null,
         ) {
-          const files = yield* readJsonFilesInTree(paths.sessionsPath);
-          const matchingSessions = new Set<string>();
+          const opencodeSessions = yield* Effect.gen(function* () {
+            const files = yield* readJsonFilesInTree(paths.sessionsPath);
+            const matchingSessions = new Set<string>();
 
-          for (const { content } of files) {
-            const parsed = parseJson<SessionInfo>(content);
-            if (parsed === null) continue;
+            for (const { content } of files) {
+              const parsed = parseJson<SessionInfo>(content);
+              if (parsed === null) continue;
 
-            if (projectDir === null || parsed.directory === projectDir) {
-              matchingSessions.add(parsed.id);
+              if (projectDir === null || parsed.directory === projectDir) {
+                matchingSessions.add(parsed.id);
+              }
             }
+
+            return matchingSessions;
+          }).pipe(
+            Effect.catchTag("SessionStorageNotFoundError", () => Effect.succeed(new Set<string>())),
+          );
+
+          const claudeSessions =
+            paths.claudeCodePath === null
+              ? new Set<string>()
+              : yield* getClaudeCodeSessions(paths.claudeCodePath, projectDir).pipe(
+                  Effect.map(
+                    (files) =>
+                      new Set<string>(
+                        files.map((filePath) => getSessionIdFromClaudeFile(filePath)),
+                      ),
+                  ),
+                  Effect.catchTag("SessionStorageNotFoundError", () =>
+                    Effect.succeed(new Set<string>()),
+                  ),
+                );
+
+          const matchingSessions = new Set<string>(opencodeSessions);
+          for (const sessionId of claudeSessions) {
+            matchingSessions.add(sessionId);
           }
 
           return matchingSessions;
@@ -149,54 +207,81 @@ export class SessionService extends ServiceMap.Service<
         getMessageSummaries: Effect.fn("SessionService.getMessageSummaries")(function* (
           filterSessions: Set<string> | null,
         ) {
-          const sessionDirs = yield* Effect.tryPromise({
-            try: async () => {
-              const dirs = await readdir(paths.messagesPath);
-              return dirs
-                .filter((name) => name.startsWith("ses_"))
-                .filter((name) => filterSessions === null || filterSessions.has(name));
-            },
-            catch: () =>
-              new SessionStorageNotFoundError({
-                message: "Message storage directory not found",
-                path: paths.messagesPath,
-              }),
-          });
+          const sourceFilter = detectSourceFilter(filterSessions);
 
-          const summaries: MessageSummary[] = [];
-
-          for (const sessionId of sessionDirs) {
-            const sessionPath = `${paths.messagesPath}/${sessionId}`;
-            const files = yield* readJsonFilesFlat(sessionPath);
-
-            for (const { filePath, content } of files) {
-              const parsed = parseJson<{
-                id?: string;
-                role?: string;
-                sessionID?: string;
-                summary?: {
-                  body?: string;
-                  title?: string;
-                };
-                time?: {
-                  created?: number;
-                };
-              }>(content);
-
-              if (parsed === null || parsed.summary?.title === undefined) {
-                continue;
-              }
+          const opencodeSummaries =
+            sourceFilter === "claude-code"
+              ? []
+              : yield* Effect.gen(function* () {
+                  const sessionDirs = yield* Effect.tryPromise({
+                    try: async () => {
+                      const dirs = await readdir(paths.messagesPath);
+                      return dirs
+                        .filter((name) => name.startsWith("ses_"))
+                        .filter((name) => filterSessions === null || filterSessions.has(name));
+                    },
+                    catch: () =>
+                      new SessionStorageNotFoundError({
+                        message: "Message storage directory not found",
+                        path: paths.messagesPath,
+                      }),
+                  });
 
-              summaries.push({
-                sessionID: parsed.sessionID ?? sessionId,
-                id: parsed.id ?? filePath.split("/").pop()?.replace(".json", "") ?? "",
-                title: parsed.summary.title,
-                body: parsed.summary.body ?? "",
-                created: parsed.time?.created ?? 0,
-                role: parsed.role ?? "unknown",
-              });
-            }
-          }
+                  const summaries: MessageSummary[] = [];
+
+                  for (const sessionId of sessionDirs) {
+                    const sessionPath = `${paths.messagesPath}/${sessionId}`;
+                    const files = yield* readJsonFilesFlat(sessionPath);
+
+                    for (const { filePath, content } of files) {
+                      const parsed = parseJson<{
+                        id?: string;
+                        role?: string;
+                        sessionID?: string;
+                        summary?: {
+                          body?: string;
+                          title?: string;
+                        };
+                        time?: {
+                          created?: number;
+                        };
+                      }>(content);
+
+                      if (parsed === null || parsed.summary?.title === undefined) {
+                        continue;
+                      }
+
+                      summaries.push({
+                        sessionID: parsed.sessionID ?? sessionId,
+                        id: parsed.id ?? filePath.split("/").pop()?.replace(".json", "") ?? "",
+                        title: parsed.summary.title,
+                        body: parsed.summary.body ?? "",
+                        created: parsed.time?.created ?? 0,
+                        role: parsed.role ?? "unknown",
+                        source: "opencode",
+                      });
+                    }
+                  }
+
+                  return summaries;
+                }).pipe(Effect.catchTag("SessionStorageNotFoundError", () => Effect.succeed([])));
+
+          const claudeSummaries =
+            sourceFilter === "opencode" || paths.claudeCodePath === null
+              ? []
+              : yield* getClaudeCodeSessions(paths.claudeCodePath, null).pipe(
+                  Effect.map((sessionFiles) =>
+                    filterSessions === null
+                      ? sessionFiles
+                      : sessionFiles.filter((sessionFile) =>
+                          filterSessions.has(getSessionIdFromClaudeFile(sessionFile)),
+                        ),
+                  ),
+                  Effect.flatMap(readClaudeCodeMessages),
+                  Effect.catchTag("SessionStorageNotFoundError", () => Effect.succeed([])),
+                );
+
+          const summaries = [...opencodeSummaries, ...claudeSummaries];
 
           return (
             summaries as MessageSummary[] & {

package/src/session-tool/types.ts

@@ -8,6 +8,8 @@ export type SessionInfo = {
   projectID: string;
 };
 
+export type SessionSource = "opencode" | "claude-code";
+
 export type MessageSummary = {
   sessionID: string;
   id: string;
@@ -15,6 +17,7 @@ export type MessageSummary = {
   body: string;
   created: number;
   role: string;
+  source: SessionSource;
 };
 
 export type SessionResult = {