Break down the @packages/opencode/src/project/ concept for me, how it relates to sessions, checkpointingg, worktrees, and sandboxes.
I want to know what exactly the data structures are of the persistence layer, and know them based on how they grow with respect to the primary agents Request context, and with respect to how the knowledge is sectioned in heirarchies for each of the agents that are active
<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project</path>
<type>directory</type>
<entries>
bootstrap.ts
instance.ts
project.sql.ts
project.ts
state.ts
vcs.ts
(6 entries)
</entries>All 4 tools executed successfully.
Keep using the batch tool for optimal performance in your next response!<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/project.ts</path>
<type>file</type>
<content>1: import z from "zod"
2: import { Filesystem } from "../util/filesystem"
3: import path from "path"
4: import { Database, eq } from "../storage/db"
5: import { ProjectTable } from "./project.sql"
6: import { SessionTable } from "../session/session.sql"
7: import { Log } from "../util/log"
8: import { Flag } from "@/flag/flag"
9: import { work } from "../util/queue"
10: import { fn } from "@opencode-ai/util/fn"
11: import { BusEvent } from "@/bus/bus-event"
12: import { iife } from "@/util/iife"
13: import { GlobalBus } from "@/bus/global"
14: import { existsSync } from "fs"
15: import { git } from "../util/git"
16: import { Glob } from "../util/glob"
17:
18: export namespace Project {
19: const log = Log.create({ service: "project" })
20: export const Info = z
21: .object({
22: id: z.string(),
23: worktree: z.string(),
24: vcs: z.literal("git").optional(),
25: name: z.string().optional(),
26: icon: z
27: .object({
28: url: z.string().optional(),
29: override: z.string().optional(),
30: color: z.string().optional(),
31: })
32: .optional(),
33: commands: z
34: .object({
35: start: z.string().optional().describe("Startup script to run when creating a new workspace (worktree)"),
36: })
37: .optional(),
38: time: z.object({
39: created: z.number(),
40: updated: z.number(),
41: initialized: z.number().optional(),
42: }),
43: sandboxes: z.array(z.string()),
44: })
45: .meta({
46: ref: "Project",
47: })
48: export type Info = z.infer<typeof Info>
49:
50: export const Event = {
51: Updated: BusEvent.define("project.updated", Info),
52: }
53:
54: type Row = typeof ProjectTable.$inferSelect
55:
56: export function fromRow(row: Row): Info {
57: con...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/project.sql.ts</path>
<type>file</type>
<content>1: import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core"
2: import { Timestamps } from "@/storage/schema.sql"
3:
4: export const ProjectTable = sqliteTable("project", {
5: id: text().primaryKey(),
6: worktree: text().notNull(),
7: vcs: text(),
8: name: text(),
9: icon_url: text(),
10: icon_color: text(),
11: ...Timestamps,
12: time_initialized: integer(),
13: sandboxes: text({ mode: "json" }).notNull().$type<string[]>(),
14: commands: text({ mode: "json" }).$type<{ start?: string }>(),
15: })
16:
(End of file - total 16 lines)
</content><path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/state.ts</path>
<type>file</type>
<content>1: import { Log } from "@/util/log"
2:
3: export namespace State {
4: interface Entry {
5: state: any
6: dispose?: (state: any) => Promise<void>
7: }
8:
9: const log = Log.create({ service: "state" })
10: const recordsByKey = new Map<string, Map<any, Entry>>()
11:
12: export function create<S>(root: () => string, init: () => S, dispose?: (state: Awaited<S>) => Promise<void>) {
13: return () => {
14: const key = root()
15: let entries = recordsByKey.get(key)
16: if (!entries) {
17: entries = new Map<string, Entry>()
18: recordsByKey.set(key, entries)
19: }
20: const exists = entries.get(init)
21: if (exists) return exists.state as S
22: const state = init()
23: entries.set(init, {
24: state,
25: dispose,
26: })
27: return state
28: }
29: }
30:
31: export async function dispose(key: string) {
32: const entries = recordsByKey.get(key)
33: if (!entries) return
34:
35: log.info("waiting for state disposal to complete", { key })
36:
37: let disposalFinished = false
38:
39: setTimeout(() => {
40: if (!disposalFinished) {
41: log.warn(
42: "state disposal is taking an unusually long time - if it does not complete in a reasonable time, please report this as a bug",
43: { key },
44: )
45: }
46: }, 10000).unref()
47:
48: const tasks: Promise<void>[] = []
49: for (const [init, entry] of entries) {
50: if (!entry.dispose) continue
51:
52: const label = typeof init === "function" ? init.name : String(init)
53:
54: const task = Promise.resolve(entry.state)
55: .then((state) => entry.dispose!(state))
56: .catch((error) => {
57: log.error("Error while disposing state:", { error, key, init: label })
58: })
5...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/instance.ts</path>
<type>file</type>
<content>1: import { Log } from "@/util/log"
2: import { Context } from "../util/context"
3: import { Project } from "./project"
4: import { State } from "./state"
5: import { iife } from "@/util/iife"
6: import { GlobalBus } from "@/bus/global"
7: import { Filesystem } from "@/util/filesystem"
8:
9: interface Context {
10: directory: string
11: worktree: string
12: project: Project.Info
13: }
14: const context = Context.create<Context>("instance")
15: const cache = new Map<string, Promise<Context>>()
16:
17: const disposal = {
18: all: undefined as Promise<void> | undefined,
19: }
20:
21: export const Instance = {
22: async provide<R>(input: { directory: string; init?: () => Promise<any>; fn: () => R }): Promise<R> {
23: let existing = cache.get(input.directory)
24: if (!existing) {
25: Log.Default.info("creating instance", { directory: input.directory })
26: existing = iife(async () => {
27: const { project, sandbox } = await Project.fromDirectory(input.directory)
28: const ctx = {
29: directory: input.directory,
30: worktree: sandbox,
31: project,
32: }
33: await context.provide(ctx, async () => {
34: await input.init?.()
35: })
36: return ctx
37: })
38: cache.set(input.directory, existing)
39: }
40: const ctx = await existing
41: return context.provide(ctx, async () => {
42: return input.fn()
43: })
44: },
45: get directory() {
46: return context.use().directory
47: },
48: get worktree() {
49: return context.use().worktree
50: },
51: get project() {
52: return context.use().project
53: },
54: /**
55: * Check if a path is within the project boundary.
56: * Returns true if path is inside Instance.directory OR Instance.worktree.
57: * Paths within the worktree but o...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session</path>
<type>directory</type>
<entries>
compaction.ts
index.ts
instruction.ts
llm.ts
message-v2.ts
message.ts
processor.ts
prompt.ts
prompt/
retry.ts
revert.ts
session.sql.ts
status.ts
summary.ts
system.ts
todo.ts
(16 entries)
</entries><path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/session.sql.ts</path>
<type>file</type>
<content>1: import { sqliteTable, text, integer, index, primaryKey } from "drizzle-orm/sqlite-core"
2: import { ProjectTable } from "../project/project.sql"
3: import type { MessageV2 } from "./message-v2"
4: import type { Snapshot } from "@/snapshot"
5: import type { PermissionNext } from "@/permission/next"
6: import { Timestamps } from "@/storage/schema.sql"
7:
8: type PartData = Omit<MessageV2.Part, "id" | "sessionID" | "messageID">
9: type InfoData = Omit<MessageV2.Info, "id" | "sessionID">
10:
11: export const SessionTable = sqliteTable(
12: "session",
13: {
14: id: text().primaryKey(),
15: project_id: text()
16: .notNull()
17: .references(() => ProjectTable.id, { onDelete: "cascade" }),
18: parent_id: text(),
19: slug: text().notNull(),
20: directory: text().notNull(),
21: title: text().notNull(),
22: version: text().notNull(),
23: share_url: text(),
24: summary_additions: integer(),
25: summary_deletions: integer(),
26: summary_files: integer(),
27: summary_diffs: text({ mode: "json" }).$type<Snapshot.FileDiff[]>(),
28: revert: text({ mode: "json" }).$type<{ messageID: string; partID?: string; snapshot?: string; diff?: string }>(),
29: permission: text({ mode: "json" }).$type<PermissionNext.Ruleset>(),
30: ...Timestamps,
31: time_compacting: integer(),
32: time_archived: integer(),
33: },
34: (table) => [index("session_project_idx").on(table.project_id), index("session_parent_idx").on(table.parent_id)],
35: )
36:
37: export const MessageTable = sqliteTable(
38: "message",
39: {
40: id: text().primaryKey(),
41: session_id: text()
42: .notNull()
43: .references(() => SessionTable.id, { onDelete: "cascade" }),
44: ...Timestamps,
45: data: text({ mode: "json" }).notNull().$type<InfoData>(),
46: },
47: (table) => [index("mes...No files foundAll 2 tools executed successfully.
Keep using the batch tool for optimal performance in your next response!Break down the @packages/opencode/src/project/ concept for me, how it relates to sessions, checkpointingg, worktrees, and sandboxes.
I want to know what exactly the data structures are of the persistence layer, and know them based on how they grow with respect to the primary agents Request context, and with respect to how the knowledge is sectioned in heirarchies for each of the agents that are active
<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project</path>
<type>directory</type>
<entries>
bootstrap.ts
instance.ts
project.sql.ts
project.ts
state.ts
vcs.ts
(6 entries)
</entries><path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/project.sql.ts</path>
<type>file</type>
<content>1: import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core"
2: import { Timestamps } from "@/storage/schema.sql"
3:
4: export const ProjectTable = sqliteTable("project", {
5: id: text().primaryKey(),
6: worktree: text().notNull(),
7: vcs: text(),
8: name: text(),
9: icon_url: text(),
10: icon_color: text(),
11: ...Timestamps,
12: time_initialized: integer(),
13: sandboxes: text({ mode: "json" }).notNull().$type<string[]>(),
14: commands: text({ mode: "json" }).$type<{ start?: string }>(),
15: })
16:
(End of file - total 16 lines)
</content>
<system-reminder>
Instructions from: /home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/AGENTS.md
# opencode database guide
## Database
- **Schema**: Drizzle schema lives in `src/**/*.sql.ts`.
- **Naming**: tables and columns use snake*case; join columns are `<entity>_id`; indexes are `<table>*<column>\_idx`.
- **Migrations**: generated by Drizzle Kit using `drizzle.config.ts` (schema: `./src/**/*.sql.ts`, output: `./migration`).
- **Command**: `bun run db generate --name <slug>`.
- **Output**: creates `migration/<timestamp>_<slug>/migration.sql` and `snapshot.json`.
- **Tests**: migration tests should read the per-folder layout (no `_journal.json`).
</system-reminder>Found 52 matches
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/cli/cmd/import.ts:
Line 5: import { MessageTable, PartTable, SessionTable } from "../../session/session.sql"
Line 133: Database.use((db) => db.insert(SessionTable).values(Session.toRow(exportData.info)).onConflictDoNothing().run())
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/test/storage/json-migration.test.ts:
Line 11: import { SessionTable, MessageTable, PartTable, TodoTable, PermissionTable } from "../../src/session/session.sql"
Line 219: const sessions = db.select().from(SessionTable).all()
Line 425: const sessions = db.select().from(SessionTable).all()
Line 457: const sessions = db.select().from(SessionTable).all()
Line 839: expect(db.select().from(SessionTable).all().length).toBe(3)
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/storage/schema.ts:
Line 2: export { SessionTable, MessageTable, PartTable, TodoTable, PermissionTable } from "../session/session.sql"
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/storage/json-migration.ts:
Line 6: import { SessionTable, MessageTable, PartTable, TodoTable, PermissionTable } from "../session/session.sql"
Line 224: stats.sessions += insert(sessionValues, SessionTable, "session")
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/share/share.sql.ts:
Line 2: import { SessionTable } from "../session/session.sql"
Line 8: .references(() => SessionTable.id, { onDelete: "cascade" }),
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/session.sql.ts:
Line 11: export const SessionTable = sqliteTable(
Line 43: .references(() => SessionTable.id, { onDelete: "cascade" }),
Line 69: .references(() => SessionTable.id, { onDelete: "cascade" }),
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/index.ts:
Line 14: import { SessionTable, MessageTable, PartTable } from "./session.sql"
Li...No files foundFound 2 matches
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/storage/db.ts:
Line 78: sqlite.run("PRAGMA wal_checkpoint(PASSIVE)")
/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/prompt/gemini.txt:
Line 111: All checks passed. This is a stable checkpoint.<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/session.sql.ts</path>
<type>file</type>
<content>1: import { sqliteTable, text, integer, index, primaryKey } from "drizzle-orm/sqlite-core"
2: import { ProjectTable } from "../project/project.sql"
3: import type { MessageV2 } from "./message-v2"
4: import type { Snapshot } from "@/snapshot"
5: import type { PermissionNext } from "@/permission/next"
6: import { Timestamps } from "@/storage/schema.sql"
7:
8: type PartData = Omit<MessageV2.Part, "id" | "sessionID" | "messageID">
9: type InfoData = Omit<MessageV2.Info, "id" | "sessionID">
10:
11: export const SessionTable = sqliteTable(
12: "session",
13: {
14: id: text().primaryKey(),
15: project_id: text()
16: .notNull()
17: .references(() => ProjectTable.id, { onDelete: "cascade" }),
18: parent_id: text(),
19: slug: text().notNull(),
20: directory: text().notNull(),
21: title: text().notNull(),
22: version: text().notNull(),
23: share_url: text(),
24: summary_additions: integer(),
25: summary_deletions: integer(),
26: summary_files: integer(),
27: summary_diffs: text({ mode: "json" }).$type<Snapshot.FileDiff[]>(),
28: revert: text({ mode: "json" }).$type<{ messageID: string; partID?: string; snapshot?: string; diff?: string }>(),
29: permission: text({ mode: "json" }).$type<PermissionNext.Ruleset>(),
30: ...Timestamps,
31: time_compacting: integer(),
32: time_archived: integer(),
33: },
34: (table) => [index("session_project_idx").on(table.project_id), index("session_parent_idx").on(table.parent_id)],
35: )
36:
37: export const MessageTable = sqliteTable(
38: "message",
39: {
40: id: text().primaryKey(),
41: session_id: text()
42: .notNull()
43: .references(() => SessionTable.id, { onDelete: "cascade" }),
44: ...Timestamps,
45: data: text({ mode: "json" }).notNull().$type<InfoData>(),
46: },
47: (table) => [index("mes...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/vcs.ts</path>
<type>file</type>
<content>1: import { BusEvent } from "@/bus/bus-event"
2: import { Bus } from "@/bus"
3: import { $ } from "bun"
4: import path from "path"
5: import z from "zod"
6: import { Log } from "@/util/log"
7: import { Instance } from "./instance"
8: import { FileWatcher } from "@/file/watcher"
9:
10: const log = Log.create({ service: "vcs" })
11:
12: export namespace Vcs {
13: export const Event = {
14: BranchUpdated: BusEvent.define(
15: "vcs.branch.updated",
16: z.object({
17: branch: z.string().optional(),
18: }),
19: ),
20: }
21:
22: export const Info = z
23: .object({
24: branch: z.string(),
25: })
26: .meta({
27: ref: "VcsInfo",
28: })
29: export type Info = z.infer<typeof Info>
30:
31: async function currentBranch() {
32: return $`git rev-parse --abbrev-ref HEAD`
33: .quiet()
34: .nothrow()
35: .cwd(Instance.worktree)
36: .text()
37: .then((x) => x.trim())
38: .catch(() => undefined)
39: }
40:
41: const state = Instance.state(
42: async () => {
43: if (Instance.project.vcs !== "git") {
44: return { branch: async () => undefined, unsubscribe: undefined }
45: }
46: let current = await currentBranch()
47: log.info("initialized", { branch: current })
48:
49: const unsubscribe = Bus.subscribe(FileWatcher.Event.Updated, async (evt) => {
50: if (evt.properties.file.endsWith("HEAD")) return
51: const next = await currentBranch()
52: if (next !== current) {
53: log.info("branch changed", { from: current, to: next })
54: current = next
55: Bus.publish(Event.BranchUpdated, { branch: next })
56: }
57: })
58:
59: return {
60: branch: async () => current,
61: unsubscribe,
62: }
63: },
64: async (state) => {
65...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/instance.ts</path>
<type>file</type>
<content>1: import { Log } from "@/util/log"
2: import { Context } from "../util/context"
3: import { Project } from "./project"
4: import { State } from "./state"
5: import { iife } from "@/util/iife"
6: import { GlobalBus } from "@/bus/global"
7: import { Filesystem } from "@/util/filesystem"
8:
9: interface Context {
10: directory: string
11: worktree: string
12: project: Project.Info
13: }
14: const context = Context.create<Context>("instance")
15: const cache = new Map<string, Promise<Context>>()
16:
17: const disposal = {
18: all: undefined as Promise<void> | undefined,
19: }
20:
21: export const Instance = {
22: async provide<R>(input: { directory: string; init?: () => Promise<any>; fn: () => R }): Promise<R> {
23: let existing = cache.get(input.directory)
24: if (!existing) {
25: Log.Default.info("creating instance", { directory: input.directory })
26: existing = iife(async () => {
27: const { project, sandbox } = await Project.fromDirectory(input.directory)
28: const ctx = {
29: directory: input.directory,
30: worktree: sandbox,
31: project,
32: }
33: await context.provide(ctx, async () => {
34: await input.init?.()
35: })
36: return ctx
37: })
38: cache.set(input.directory, existing)
39: }
40: const ctx = await existing
41: return context.provide(ctx, async () => {
42: return input.fn()
43: })
44: },
45: get directory() {
46: return context.use().directory
47: },
48: get worktree() {
49: return context.use().worktree
50: },
51: get project() {
52: return context.use().project
53: },
54: /**
55: * Check if a path is within the project boundary.
56: * Returns true if path is inside Instance.directory OR Instance.worktree.
57: * Paths within the worktree but o...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/project/project.ts</path>
<type>file</type>
<content>1: import z from "zod"
2: import { Filesystem } from "../util/filesystem"
3: import path from "path"
4: import { Database, eq } from "../storage/db"
5: import { ProjectTable } from "./project.sql"
6: import { SessionTable } from "../session/session.sql"
7: import { Log } from "../util/log"
8: import { Flag } from "@/flag/flag"
9: import { work } from "../util/queue"
10: import { fn } from "@opencode-ai/util/fn"
11: import { BusEvent } from "@/bus/bus-event"
12: import { iife } from "@/util/iife"
13: import { GlobalBus } from "@/bus/global"
14: import { existsSync } from "fs"
15: import { git } from "../util/git"
16: import { Glob } from "../util/glob"
17:
18: export namespace Project {
19: const log = Log.create({ service: "project" })
20: export const Info = z
21: .object({
22: id: z.string(),
23: worktree: z.string(),
24: vcs: z.literal("git").optional(),
25: name: z.string().optional(),
26: icon: z
27: .object({
28: url: z.string().optional(),
29: override: z.string().optional(),
30: color: z.string().optional(),
31: })
32: .optional(),
33: commands: z
34: .object({
35: start: z.string().optional().describe("Startup script to run when creating a new workspace (worktree)"),
36: })
37: .optional(),
38: time: z.object({
39: created: z.number(),
40: updated: z.number(),
41: initialized: z.number().optional(),
42: }),
43: sandboxes: z.array(z.string()),
44: })
45: .meta({
46: ref: "Project",
47: })
48: export type Info = z.infer<typeof Info>
49:
50: export const Event = {
51: Updated: BusEvent.define("project.updated", Info),
52: }
53:
54: type Row = typeof ProjectTable.$inferSelect
55:
56: export function fromRow(row: Row): Info {
57: con...<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/index.ts</path>
<type>file</type>
<content>1: import { Slug } from "@opencode-ai/util/slug"
2: import path from "path"
3: import { BusEvent } from "@/bus/bus-event"
4: import { Bus } from "@/bus"
5: import { Decimal } from "decimal.js"
6: import z from "zod"
7: import { type ProviderMetadata } from "ai"
8: import { Config } from "../config/config"
9: import { Flag } from "../flag/flag"
10: import { Identifier } from "../id/id"
11: import { Installation } from "../installation"
12:
13: import { Database, NotFoundError, eq, and, or, gte, isNull, desc, like } from "../storage/db"
14: import { SessionTable, MessageTable, PartTable } from "./session.sql"
15: import { Storage } from "@/storage/storage"
16: import { Log } from "../util/log"
17: import { MessageV2 } from "./message-v2"
18: import { Instance } from "../project/instance"
19: import { SessionPrompt } from "./prompt"
20: import { fn } from "@/util/fn"
21: import { Command } from "../command"
22: import { Snapshot } from "@/snapshot"
23:
24: import type { Provider } from "@/provider/provider"
25: import { PermissionNext } from "@/permission/next"
26: import { Global } from "@/global"
27: import type { LanguageModelV2Usage } from "@ai-sdk/provider"
28: import { iife } from "@/util/iife"
29:
30: export namespace Session {
31: const log = Log.create({ service: "session" })
32:
33: const parentTitlePrefix = "New session - "
34: const childTitlePrefix = "Child session - "
35:
36: function createDefaultTitle(isChild = false) {
37: return (isChild ? childTitlePrefix : parentTitlePrefix) + new Date().toISOString()
38: }
39:
40: export function isDefaultTitle(title: string) {
41: return new RegExp(
42: `^(${parentTitlePrefix}|${childTitlePrefix})\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$`,
43: ).test(title)
44: }
45:
46: type SessionRow = typeof SessionTable.$inferSelect
47:
48: export functio...No files found<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/util/context.ts</path>
<type>file</type>
<content>1: import { AsyncLocalStorage } from "async_hooks"
2:
3: export namespace Context {
4: export class NotFound extends Error {
5: constructor(public override readonly name: string) {
6: super(`No context found for ${name}`)
7: }
8: }
9:
10: export function create<T>(name: string) {
11: const storage = new AsyncLocalStorage<T>()
12: return {
13: use() {
14: const result = storage.getStore()
15: if (!result) {
16: throw new NotFound(name)
17: }
18: return result
19: },
20: provide<R>(value: T, fn: () => R) {
21: return storage.run(value, fn)
22: },
23: }
24: }
25: }
26:
(End of file - total 26 lines)
</content>No files found<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/opencode/src/session/prompt.ts</path>
<type>file</type>
<content>1: import path from "path"
2: import os from "os"
3: import fs from "fs/promises"
4: import z from "zod"
5: import { Filesystem } from "../util/filesystem"
6: import { Identifier } from "../id/id"
7: import { MessageV2 } from "./message-v2"
8: import { Log } from "../util/log"
9: import { SessionRevert } from "./revert"
10: import { Session } from "."
11: import { Agent } from "../agent/agent"
12: import { Provider } from "../provider/provider"
13: import { type Tool as AITool, tool, jsonSchema, type ToolCallOptions, asSchema } from "ai"
14: import { SessionCompaction } from "./compaction"
15: import { Instance } from "../project/instance"
16: import { Bus } from "../bus"
17: import { ProviderTransform } from "../provider/transform"
18: import { SystemPrompt } from "./system"
19: import { InstructionPrompt } from "./instruction"
20: import { Plugin } from "../plugin"
21: import PROMPT_PLAN from "../session/prompt/plan.txt"
22: import BUILD_SWITCH from "../session/prompt/build-switch.txt"
23: import MAX_STEPS from "../session/prompt/max-steps.txt"
24: import { defer } from "../util/defer"
25: import { ToolRegistry } from "../tool/registry"
26: import { MCP } from "../mcp"
27: import { LSP } from "../lsp"
28: import { ReadTool } from "../tool/read"
29: import { FileTime } from "../file/time"
30: import { Flag } from "../flag/flag"
31: import { ulid } from "ulid"
32: import { spawn } from "child_process"
33: import { Command } from "../command"
34: import { $, fileURLToPath, pathToFileURL } from "bun"
35: import { ConfigMarkdown } from "../config/markdown"
36: import { SessionSummary } from "./summary"
37: import { NamedError } from "@opencode-ai/util/error"
38: import { fn } from "@/util/fn"
39: import { SessionProcessor } from "./processor"
40: import { TaskTool } from "@/tool/task"
41: import { Tool } from "@/tool/tool"
42: import { PermissionNext ...Wrote file successfully.Edit applied successfully.Edit applied successfully.<path>/home/jm/data/code/opencode-trees/ChyTQ/packages/web/src/content/docs/docs/index.mdx</path>
<type>file</type>
<content>1: ---
2: title: Intro
3: description: Get started with OpenCode.
4: ---
5:
6: import { Tabs, TabItem } from "@astrojs/starlight/components"
7: import config from "../../../../config.mjs"
8: export const console = config.console
9:
10: [**OpenCode**](/) is an open source AI coding agent. It's available as a terminal-based interface, desktop app, or IDE extension.
11:
12: 
13:
14: Let's get started.
15:
16: ---
17:
18: #### Prerequisites
19:
20: To use OpenCode in your terminal, you'll need:
21:
22: 1. A modern terminal emulator like:
23: - [WezTerm](https://wezterm.org), cross-platform
24: - [Alacritty](https://alacritty.org), cross-platform
25: - [Ghostty](https://ghostty.org), Linux and macOS
26: - [Kitty](https://sw.kovidgoyal.net/kitty/), Linux and macOS
27:
28: 2. API keys for the LLM providers you want to use.
29:
30: ---
31:
32: ## Install
33:
34: The easiest way to install OpenCode is through the install script.
35:
36: ```bash
37: curl -fsSL https://opencode.ai/install | bash
38: ```
39:
40: You can also install it with the following commands:
41:
42: - **Using Node.js**
43:
44: <Tabs>
45:
46: <TabItem label="npm">
47: ```bash
48: npm install -g opencode-ai
49: ```
50:
51: </TabItem>
52:
53: <TabItem label="Bun">
54: ```bash
55: bun install -g opencode-ai
56: ```
57:
58: </TabItem>
59:
60: <TabItem label="pnpm">
61: ```bash
62: pnpm install -g opencode-ai
63: ```
64:
65: </TabItem>
66:
67: <TabItem label="Yarn">
68: ```bash
69: yarn global add opencode-ai
70: ```
71:
72: </TabItem>
73:
74: </Tabs>
75:
76: - **Using Homebrew on macOS and Linux**
77:
78: ``...Edit applied successfully.The following paths are ignored by one of your .gitignore files:
packages/web/src/content/docs
hint: Use -f if you really want to add them.
hint: Disable this message with "git config set advice.addIgnoredFile false"
<path>/home/jm/data/code/opencode-trees/ChyTQ/.gitignore</path>
<type>file</type>
<content>1: .DS_Store
2: node_modules
3: .worktrees
4: .sst
5: .env
6: .idea
7: .vscode
8: .codex
9: *~
10: playground
11: tmp
12: dist
13: ts-dist
14: .turbo
15: **/.serena
16: .serena/
17: /result
18: refs
19: Session.vim
20: opencode.json
21: a.out
22: target
23: .scripts
24: .direnv/
25:
26: # Local dev files
27: opencode-dev
28: logs/
29: *.bun-build
30:
31: # SST generated files (tracked ones in console/* stay tracked)
32: sst-env.d.ts
33: packages/*/sst-env.d.ts
34:
35: # Wrangler generated types
36: worker-configuration.d.ts
37:
38: # Astro build output
39: packages/web/.astro/
40:
41: # OpenProse runtime state
42: .prose/
43:
44: # AST experiment artifacts
45: .ast/
46:
47: # OpenCode personal config (skills, themes, agent artifacts)
48: .opencode/skill/
49: .opencode/themes/
50: .opencode/context/project/
51: .opencode/project/
52: .opencode/agent/researcher.md
53:
54: # Fork-specific web docs (AI-generated dev notes)
55: packages/web/docs/
56:
57: # Backup files
58: *.backup
59:
60: # Private keys
61: private.key
62: *.pem
63:
64: # AST-grep config (references deleted .ast/ dir)
65: sgconfig.yml
66:
67: # Fork experiment files in packages/opencode
68: packages/opencode/Dockerfile.minimal
69: packages/opencode/env.d.ts
70: packages/opencode/vite.config.minimal.ts
71: packages/opencode/wrangler.jsonc
72:
73: .branchlet.json
74: packages/web/src/content/i18n/*.json
75:
(End of file - total 75 lines)
</content>/home/jm/data/code/opencode/.git/info/exclude:3:packages/web/src/content/docs packages/web/src/content/docs/docs/architecture.mdx
packages/web/src/content/docs/docs/index.mdx
[claude/optimize-capnweb-integration-ChyTQ 7f554d403] docs: break down project and session architecture
1 file changed, 71 insertions(+)
create mode 100644 packages/web/src/content/docs/docs/architecture.mdx
The architecture of OpenCode's persistence and workspace management layers is centered around the relationship between projects, sessions, and sandboxes. Here is a breakdown of the core concepts and data structures.
Persistence layer, session hierarchies, and workspace management logic
Projects are identified by the root commit hash of a git repository.
This allows the system to track a project even if the directory is renamed or moved.
The persistence layer stores project metadata in a dedicated table.
This includes the primary worktree path and a list of active sandboxes.
const ProjectTable = sqliteTable("project", {
id: text().primaryKey(),
worktree: text().notNull(),
sandboxes: text({ mode: "json" }).notNull()
})
Sessions represent individual conversation threads tied to a specific project.
They are organized in a hierarchy using parent identifiers to support forks and subtasks.
Data grows linearly as messages and parts are added to a session.
The schema separates messages from their constituent parts for granular tracking.
A workspace consists of a common worktree and one or more sandboxes.
The worktree is the shared git directory, while sandboxes are specific checkouts.
Instances provide the runtime context for a given working directory.
They resolve the relationship between the current path, the project, and the sandbox.
Checkpointing is handled through a revert mechanism stored on the session.
It captures message identifiers and snapshots to allow rolling back state.
const SessionTable = sqliteTable("session", {
id: text().primaryKey(),
revert: text({ mode: "json" }).$type<{
messageID: string
snapshot?: string
}>()
})
Summary fields track file changes and diffs across the session history.
This provides the agent with a compressed view of the current work state.
Knowledge is sectioned into hierarchies based on the active agent and session depth.
Primary agents use the full session history as their request context.
Subagents operate in isolated contexts with restricted permissions and specialized instructions.
This prevents context pollution while allowing deep exploration of specific tasks.
I have committed these changes to packages/web/src/content/docs/docs/architecture.mdx.