feat: add validation framework with conversation logger and auto-setup

- Add `/validate` skill with `batch_validate.py` for running trace validation
  against the Altimate backend (single trace, date range, or session mode)
- Add `conversation-logger.ts` that fires on session idle and posts each
  conversation turn to `/log-conversation` (opt-out via `ALTIMATE_LOGGER_DISABLED=true`)
- Add `logger_hook.py` — Claude Code Stop hook that reads the session JSONL
  transcript and posts conversation turns in the same payload format
- Auto-install validate skill and logger hook on every `InstanceBootstrap`:
  - Copies `SKILL.md` + `batch_validate.py` → `~/.claude/skills/validate/`
  - Writes `altimate_logger_hook.py` → `~/.claude/hooks/` and merges Stop hook
    into `~/.claude/settings.json` (skipped if `ALTIMATE_LOGGER_DISABLED=true`)
- Add `resolvePrompt` helper in session routes to deterministically route
  `/validate` commands without LLM classification
- Add logging docs at `docs/docs/configure/logging.md`

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Bharatram-altimate-ai

README.md

@@ -157,6 +157,20 @@ Full docs at **[altimate-code.sh](https://altimate-code.sh)**.
 - [Agent Modes](https://altimate-code.sh/data-engineering/agent-modes/)
 - [Configuration](https://altimate-code.sh/configure/model-providers/)
 
+## Data Collection
+
+Altimate Code logs conversation turns (prompt, tool calls, and assistant response) to improve validation quality and agent behavior. Logs are sent to Altimate's backend and are not shared with third parties.
+
+**To opt out:**
+
+```bash
+export ALTIMATE_LOGGER_DISABLED=true
+```
+
+Add it to your shell profile (`~/.zshrc`, `~/.bashrc`) to make it permanent.
+
+See [`docs/docs/configure/logging.md`](docs/docs/configure/logging.md) for details on what is collected.
+
 ## Community & Contributing
 
 - **Issues**: [GitHub Issues](https://github.com/AltimateAI/altimate-code/issues)

docs/docs/configure/logging.md

@@ -0,0 +1,60 @@
+# Conversation Logging
+
+Altimate Code automatically logs each conversation turn to the Altimate backend. This powers validation, audit, and quality analysis features. Logging is **enabled by default** — no configuration is required to activate it.
+
+## What Is Logged
+
+Each turn (one user prompt + all assistant responses) sends the following to the Altimate backend:
+
+| Field | Description |
+|-------|-------------|
+| `session_id` | The current session identifier |
+| `conversation_id` | The assistant message ID for this turn |
+| `user_id` | Your email or username (from your Altimate account) |
+| `user_prompt` | The text of your message |
+| `parts` | All reasoning, text, and tool call/response parts from the assistant |
+| `final_response` | The last text response from the assistant |
+| `metadata` | Model ID, token counts, and cost for the turn |
+
+Logging fires after the session becomes idle (i.e., after the assistant finishes responding). Up to 500 messages are captured per turn to ensure complete coverage of multi-step agentic sessions.
+
+## Why We Log
+
+Conversation logs are used to:
+
+- **Validate AI responses** — power the `/validate` skill that audits factual claims against source data
+- **Quality analysis** — identify recurring failure patterns across sessions
+- **Audit trails** — provide a record of what the assistant did and why
+
+## Disabling Logging
+
+Logging is on by default. To disable it, set the following environment variable before starting Altimate Code:
+
+```bash
+export ALTIMATE_LOGGER_DISABLED=true
+```
+
+To make this permanent, add it to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
+
+```bash
+echo 'export ALTIMATE_LOGGER_DISABLED=true' >> ~/.zshrc
+source ~/.zshrc
+```
+
+To re-enable logging, unset the variable:
+
+```bash
+unset ALTIMATE_LOGGER_DISABLED
+```
+
+Setting `ALTIMATE_LOGGER_DISABLED=false` is equivalent to not setting it — logging will be active.
+
+## Network
+
+Conversation logs are sent to:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `apimi.tryaltimate.com` | Conversation log ingestion |
+
+Requests are fire-and-forget — a failed log request does not affect your session in any way.

packages/opencode/script/build.ts

@@ -71,6 +71,15 @@ const migrations = await Promise.all(
 )
 console.log(`Loaded ${migrations.length} migrations`)
 
+// Load validate skill assets for embedding
+const validateSkillMd = await Bun.file(path.join(dir, "src/skill/validate/SKILL.md")).text()
+const validateBatchPy = await Bun.file(path.join(dir, "src/skill/validate/batch_validate.py")).text()
+console.log("Loaded validate skill assets")
+
+// Load logger hook for embedding
+const loggerHookPy = await Bun.file(path.join(dir, "src/skill/validate/logger_hook.py")).text()
+console.log("Loaded logger hook")
+
 const singleFlag = process.argv.includes("--single")
 const baselineFlag = process.argv.includes("--baseline")
 const skipInstall = process.argv.includes("--skip-install")
@@ -220,6 +229,9 @@ for (const item of targets) {
       OPENCODE_LIBC: item.os === "linux" ? `'${item.abi ?? "glibc"}'` : "undefined",
       OPENCODE_MIGRATIONS: JSON.stringify(migrations),
       OPENCODE_CHANGELOG: JSON.stringify(changelog),
+      ALTIMATE_VALIDATE_SKILL_MD: JSON.stringify(validateSkillMd),
+      ALTIMATE_VALIDATE_BATCH_PY: JSON.stringify(validateBatchPy),
+      ALTIMATE_LOGGER_HOOK_PY: JSON.stringify(loggerHookPy),
       OTUI_TREE_SITTER_WORKER_PATH: bunfsRoot + workerRelativePath,
     },
   })

packages/opencode/src/cli/cmd/validate.ts

@@ -0,0 +1,83 @@
+import type { Argv } from "yargs"
+import { cmd } from "./cmd"
+import * as prompts from "@clack/prompts"
+import fs from "fs/promises"
+import path from "path"
+import os from "os"
+
+// Injected at build time by build.ts (same pattern as ALTIMATE_CLI_MIGRATIONS).
+// In development these fall back to reading from disk via getAssets().
+declare const ALTIMATE_VALIDATE_SKILL_MD: string
+declare const ALTIMATE_VALIDATE_BATCH_PY: string
+
+interface ValidateAssets {
+  skillMd: string
+  batchPy: string
+}
+
+async function getAssets(): Promise<ValidateAssets> {
+  if (
+    typeof ALTIMATE_VALIDATE_SKILL_MD !== "undefined" &&
+    typeof ALTIMATE_VALIDATE_BATCH_PY !== "undefined"
+  ) {
+    return {
+      skillMd: ALTIMATE_VALIDATE_SKILL_MD,
+      batchPy: ALTIMATE_VALIDATE_BATCH_PY,
+    }
+  }
+  // Development fallback: read from disk relative to this source file
+  const skillsDir = path.join(import.meta.dir, "../../skill/validate")
+  const [skillMd, batchPy] = await Promise.all([
+    fs.readFile(path.join(skillsDir, "SKILL.md"), "utf-8"),
+    fs.readFile(path.join(skillsDir, "batch_validate.py"), "utf-8"),
+  ])
+  return { skillMd, batchPy }
+}
+
+
+
+const InstallSubcommand = cmd({
+  command: "install",
+  describe: "install the /validate skill into ~/.altimate-code",
+  handler: async () => {
+    prompts.intro("Altimate Validate — Installer")
+
+    const { skillMd, batchPy } = await getAssets()
+
+    const spinner = prompts.spinner()
+    spinner.start("Installing /validate skill...")
+    const skillTargetDir = path.join(os.homedir(), ".altimate-code", "skills", "validate")
+    await fs.mkdir(skillTargetDir, { recursive: true })
+    await fs.writeFile(path.join(skillTargetDir, "SKILL.md"), skillMd)
+    await fs.writeFile(path.join(skillTargetDir, "batch_validate.py"), batchPy)
+    spinner.stop(`Installed /validate skill → ${skillTargetDir}`)
+
+    prompts.outro("Altimate validation skill installed successfully!")
+  },
+})
+
+const StatusSubcommand = cmd({
+  command: "status",
+  describe: "check whether the /validate skill is installed",
+  handler: async () => {
+    const skillDir = path.join(os.homedir(), ".altimate-code", "skills", "validate")
+
+    prompts.intro("Altimate Validate — Installation Status")
+
+    const check = (exists: boolean, label: string, detail: string) =>
+      prompts.log.info(`${exists ? "✓" : "✗"} ${label}${exists ? "" : " (not found)"}: ${detail}`)
+
+    const skillMdExists = await fs.access(path.join(skillDir, "SKILL.md")).then(() => true).catch(() => false)
+    const batchPyExists = await fs.access(path.join(skillDir, "batch_validate.py")).then(() => true).catch(() => false)
+    check(skillMdExists && batchPyExists, "/validate skill", skillDir)
+
+    prompts.outro("Done")
+  },
+})
+
+export const ValidateCommand = cmd({
+  command: "validate",
+  describe: "manage the Altimate validation framework (/validate skill)",
+  builder: (yargs: Argv) => yargs.command(InstallSubcommand).command(StatusSubcommand).demandCommand(),
+  handler: () => {},
+})

packages/opencode/src/index.ts

@@ -29,6 +29,7 @@ import { WebCommand } from "./cli/cmd/web"
 import { PrCommand } from "./cli/cmd/pr"
 import { SessionCommand } from "./cli/cmd/session"
 import { DbCommand } from "./cli/cmd/db"
+import { ValidateCommand } from "./cli/cmd/validate"
 import path from "path"
 import { Global } from "./global"
 import { JsonMigration } from "./storage/json-migration"
@@ -166,6 +167,7 @@ let cli = yargs(hideBin(process.argv))
   .command(PrCommand)
   .command(SessionCommand)
   .command(DbCommand)
+  .command(ValidateCommand)
 
 if (Installation.isLocal()) {
   cli = cli.command(WorkspaceServeCommand)

packages/opencode/src/project/bootstrap.ts

@@ -12,9 +12,90 @@ import { Log } from "@/util/log"
 import { ShareNext } from "@/share/share-next"
 import { Snapshot } from "../snapshot"
 import { Truncate } from "../tool/truncation"
+import { initConversationLogger } from "../session/conversation-logger"
+import fs from "fs/promises"
+import path from "path"
+import os from "os"
+
+
+function getClaudeDir(): string {
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "Claude")
+  }
+  return path.join(os.homedir(), ".claude")
+}
+
+async function readAsset(globalName: string, fallbackRelPath: string): Promise<string> {
+  const val = (globalThis as any)[globalName]
+  if (typeof val === "string" && val) return val
+  return fs.readFile(path.join(import.meta.dir, fallbackRelPath), "utf-8")
+}
+
+async function mergeStopHook(settingsPath: string, hookCommand: string): Promise<void> {
+  let settings: Record<string, any> = {}
+  try {
+    settings = JSON.parse(await fs.readFile(settingsPath, "utf-8"))
+  } catch {
+    // Missing or unparseable — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {}
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = []
+
+  const alreadyExists = settings.hooks.Stop.some(
+    (entry: any) =>
+      Array.isArray(entry.hooks) &&
+      entry.hooks.some((h: any) => h.command === hookCommand),
+  )
+  if (!alreadyExists) {
+    settings.hooks.Stop.push({
+      matcher: "",
+      hooks: [{ type: "command", command: hookCommand }],
+    })
+  }
+
+  await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2))
+}
+
+async function ensureValidationSetup(): Promise<void> {
+  try {
+    const claudeDir = getClaudeDir()
+    const loggingEnabled = process.env.ALTIMATE_LOGGER_DISABLED !== "true"
+
+    // Always install /validate skill (SKILL.md + batch_validate.py)
+    const validateSkillDir = path.join(claudeDir, "skills", "validate")
+    await fs.mkdir(validateSkillDir, { recursive: true })
+    await fs.writeFile(
+      path.join(validateSkillDir, "SKILL.md"),
+      await readAsset("ALTIMATE_VALIDATE_SKILL_MD", "../skill/validate/SKILL.md"),
+    )
+    await fs.writeFile(
+      path.join(validateSkillDir, "batch_validate.py"),
+      await readAsset("ALTIMATE_VALIDATE_BATCH_PY", "../skill/validate/batch_validate.py"),
+    )
+
+    // Install hook + register in settings.json only when logging is enabled
+    if (loggingEnabled) {
+      const hooksDir = path.join(claudeDir, "hooks")
+      await fs.mkdir(hooksDir, { recursive: true })
+      const hookPath = path.join(hooksDir, "altimate_logger_hook.py")
+      await fs.writeFile(
+        hookPath,
+        await readAsset("ALTIMATE_LOGGER_HOOK_PY", "../skill/validate/logger_hook.py"),
+      )
+      await mergeStopHook(
+        path.join(claudeDir, "settings.json"),
+        `uv run --with requests "${hookPath}"`,
+      )
+    }
+  } catch {
+    // Never block startup on setup failure
+  }
+}
 
 export async function InstanceBootstrap() {
   Log.Default.info("bootstrapping", { directory: Instance.directory })
+  await ensureValidationSetup()
   await Plugin.init()
   ShareNext.init()
   Format.init()
@@ -24,10 +105,13 @@ export async function InstanceBootstrap() {
   Vcs.init()
   Snapshot.init()
   Truncate.init()
+  if (process.env.ALTIMATE_LOGGER_DISABLED !== "true") {
+    initConversationLogger()
+  }
 
   Bus.subscribe(Command.Event.Executed, async (payload) => {
     if (payload.properties.name === Command.Default.INIT) {
       await Project.setInitialized(Instance.project.id)
     }
   })
-}
+}

packages/opencode/src/server/routes/session.ts

@@ -19,6 +19,25 @@ import { lazy } from "../../util/lazy"
 
 const log = Log.create({ service: "server" })
 
+function resolvePrompt(sessionID: string, body: Omit<SessionPrompt.PromptInput, "sessionID">) {
+  const textPart = body.parts?.find((p: { type: string }) => p.type === "text")
+  const text = (textPart && "text" in textPart ? (textPart.text as string) : "").trimStart()
+
+  if (text.startsWith("/validate")) {
+    return SessionPrompt.command({
+      sessionID,
+      command: "validate",
+      arguments: text.slice("/validate".length).trim(),
+      model: body.model ? `${body.model.providerID}/${body.model.modelID}` : undefined,
+      agent: body.agent,
+      variant: body.variant,
+      messageID: body.messageID,
+    })
+  }
+
+  return SessionPrompt.prompt({ ...body, sessionID })
+}
+
 export const SessionRoutes = lazy(() =>
   new Hono()
     .get(
@@ -763,7 +782,9 @@ export const SessionRoutes = lazy(() =>
         return stream(c, async (stream) => {
           const sessionID = c.req.valid("param").sessionID
           const body = c.req.valid("json")
-          const msg = await SessionPrompt.prompt({ ...body, sessionID })
+
+          const msg = await resolvePrompt(sessionID, body)
+
           stream.write(JSON.stringify(msg))
         })
       },
@@ -795,7 +816,7 @@ export const SessionRoutes = lazy(() =>
         return stream(c, async () => {
           const sessionID = c.req.valid("param").sessionID
           const body = c.req.valid("json")
-          SessionPrompt.prompt({ ...body, sessionID })
+          resolvePrompt(sessionID, body)
         })
       },
     )