Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import type { PanelEditableSettings, PanelSettings } from "./model.js";
/**
* The settings modal's model (Story 8.13): one description per field, the
* sections it is laid out in, and the values shown when the page was built
* before the current setting changed. Runtime-free so the template can import
* it and tests can check the modal without a DOM.
*
* Every field also carries a `details` text: the longer plain-language answer
* the "?" next to its label opens (Story 12.1). `cogit config --help` prints
* the same text, so the two never drift.
*/
/** What a setting's control looks like. */
export type SettingKind = "text" | "number" | "boolean" | "select";
export interface SettingOption {
value: string;
label: string;
}
export interface SettingField {
key: keyof PanelSettings;
label: string;
/** One short line under the label, so nobody has to read the docs. */
help: string;
/** The longer explanation behind "?" (Story 12.1). Plain language, no keys. */
details: string;
kind: SettingKind;
/** The choices of a `select`. */
options?: SettingOption[];
/** False over `file://` and for the setup-time keys the modal only shows. */
editable: boolean;
}
export interface SettingsSection {
title: string;
fields: SettingField[];
}
export interface FieldSpec {
key: keyof PanelSettings;
label: string;
help: string;
details: string;
kind: SettingKind;
options?: SettingOption[];
}
const EDITABLE: FieldSpec[] = [
{
key: "recorder",
label: "Recording",
help: "How much of the chat goes into the record.",
details:
"Economical (recommended): a small model records in the background every few turns and " +
"closes each session with one pass that finds its threads, writes the branch summaries " +
"and one line on where the session left off. The agent is never interrupted; it costs " +
"under 2 cents per 20 messages. Detailed: on top of that, the main agent records its own " +
"decisions every 15 turns. It catches the agent's technical choices best and costs about " +
"1–2% of a session. A third mode, where only the main agent records, is set with " +
"`cogit config set recorder agent`.",
kind: "select",
options: [
{ value: "side", label: "Economical (recommended)" },
{ value: "mixed", label: "Detailed" },
],
},
{
key: "messageSummaries",
label: "One-line summary under each message",
help: "A sentence under each message title on the map.",
details:
"A one-sentence summary under each message title: what came of it. Without it, a " +
"message that only discussed or advised keeps nothing but its title. Off keeps the " +
"record shorter and cheaper. Branch summaries and the line on where a session left " +
"off are written either way.",
kind: "boolean",
},
{
key: "startupContext",
label: "Record at session start",
help: "Hand the agent the previous session's record when a chat starts.",
details:
"When a chat starts, the agent gets a short summary of where the previous session left " +
"off and how to read the record. It costs a few tokens; turn it off if your projects " +
"are unrelated.",
kind: "boolean",
},
{
key: "recordHeadless",
label: "Headless sessions",
help: "Record sessions that start without a person, such as `claude -p`.",
details:
"Some plugins and scripts run `claude -p` in the background, often once per prompt. " +
"Off, cogit leaves those sessions out of the map and the inbox. Turn it on if you do " +
"real work through `claude -p` or the SDK and want it recorded.",
kind: "boolean",
},
{
key: "tryBeforeNotes",
label: "Tried-before notes",
help: "Before the agent edits a file, tell it which options earlier thoughts rejected for it.",
details:
"Before the agent edits a file, it hears which options earlier thoughts tried and " +
"rejected for that file. These are notes from the record, never rules; they can make " +
"the agent ask before repeating a dead end.",
kind: "boolean",
},
{
key: "shapes",
label: "Intent, Shape and Code",
help: "A small picture of what each change does, beside its reason and its diff.",
details:
"For every message that landed commits, a small representation of what the change does: " +
"numbered plain-language steps or a Mermaid diagram. It sits between the record's intent " +
"(the decision, reason and rejected options) and the code (the diff), so a reviewer sees " +
"why, what and how in one place. The recorder writes it, not you; it costs one small " +
"model call per such message. Off, the map says so and nothing is written.",
kind: "boolean",
},
{
key: "captures",
label: "Tasks",
help: "A short list of what each session left undone, drafted by the side model.",
details:
"When a session ends, the side model reads what its record left open and drafts at " +
"most three things a person would ask for, in the conversation's language. The list " +
"is yours: accept, dismiss or close each item. Sessions with nothing open cost no " +
"model call; the map's Tasks button appears only while something waits or is open. " +
"Off, nothing is drafted and the list already in the store is kept, not deleted.",
kind: "boolean",
},
{
key: "language",
label: "Language",
help: "Language the agent writes records in; `auto` follows the chat.",
details:
"The language the record is written in. With auto, it follows the language of the " +
"conversation.",
kind: "text",
},
{
key: "shareConversations",
label: "Share conversations",
help: "Send the raw chat text too, not only the session record (off: chat stays local).",
details:
"In a project that shares its record, also send the raw chat text. Leave it off to keep " +
"conversations on your machine while teammates still see titles, decisions and reasons.",
kind: "boolean",
},
];
/** A setting only `cogit config` changes: per project, set up once, or rarely touched. */
export interface CliSetting {
key: string;
label: string;
help: string;
details: string;
}
/** The settings the panel leaves out; `cogit config --help` and the guide explain them. */
export const CLI_ONLY: CliSetting[] = [
{
key: "updateEveryTurns",
label: "Record every N turns",
help: "Ask the agent to record after this many turns.",
details:
"How often the main agent is asked to update the record inside the chat. In mixed mode " +
"the side model records in between, so this can be rare (15 turns by default).",
},
{
key: "sideEveryTurns",
label: "Side model every N turns",
help: "How often the background recorder writes in mixed or side mode.",
details:
"How often the small side model records in the background. A lower number keeps the " +
"map fresher and costs a little more; a higher number is quieter.",
},
{
key: "sessionEndCatchUp",
label: "Side model at session end",
help: "When a session ends, the side model records what is left and closes the session.",
details:
"When a session ends, the side model records whatever nobody got to, then reads the " +
"whole session once to find its threads, write the branch summaries and one line on " +
"where it left off. It runs outside the chat, so it does not spend the session's tokens.",
},
{
key: "sideModel",
label: "Side model",
help: "The small model that records outside the chat.",
details:
"The small model behind every side record: every few turns in mixed mode, all the " +
"time in side mode, and at session end. Haiku is cheap and good enough for titles, " +
"parents and short decisions.",
},
{
key: "agents",
label: "Agents",
help: "Which agents record lineage; change it with `cogit config set`.",
details:
"Which AI agents in this project should record what they are asked and what they " +
"decide. Claude Code is the only one today.",
},
{
key: "inboxMaxAgeDays",
label: "Inbox age",
help: 'Days a waiting session stays in the "Your turn" inbox.',
details:
"A session that waits on you longer than this leaves the inbox. It is hidden, not " +
"deleted: the map still has it.",
},
{
key: "bigChangeLines",
label: "Big change",
help: "Lines of code after which a message counts as a big change on the map.",
details:
"Messages whose commits changed at least this many lines get a quiet mark on the " +
"map and in the message details. It never hides or ranks anything by itself.",
},
{
key: "trailerMaxAgeHours",
label: "Trailer age",
help: "How old the last message may be for a commit to get its `Thought:` trailer.",
details:
"A commit made hours after the last message is probably not about that message, so " +
"past this age the commit gets no trailer instead of a wrong one.",
},
{
key: "serverPort",
label: "Server port",
help: "Port of the local map server on 127.0.0.1.",
details: "Change it only when another program already uses the port.",
},
];
/**
* One section today, "Recording", so later groups slot in without a redesign.
* Over `file://` (`canEdit` false) the editable fields still appear, read-only,
* with the build-time values. The CLI-only settings (`CLI_ONLY`) stay out of
* the panel: they are per project, set up once or rarely touched.
*/
/** The panel's settings in their order, for the guide. */
export function panelSettingFields(): readonly FieldSpec[] {
return EDITABLE;
}
export function settingsSections(canEdit: boolean): SettingsSection[] {
return [
{
title: "Recording",
fields: EDITABLE.map((field) => ({ ...field, editable: canEdit })),
},
];
}
/** The long plain-language text of one setting, for `cogit config --help`. */
export function configHelpLines(): string[] {
return [...EDITABLE, ...CLI_ONLY].map(
(field) => ` ${field.key}\n ${field.label}: ${field.help}\n ${field.details}`,
);
}
/**
* The values a modal starts with when no server answers (a `file://` page):
* the defaults from the config schema, overridden by what the build embedded.
*/
export const DEFAULT_SETTINGS: PanelSettings = {
recorder: "side",
language: "auto",
updateEveryTurns: 15,
sideEveryTurns: 5,
sessionEndCatchUp: true,
sideModel: "haiku",
messageSummaries: true,
startupContext: true,
recordHeadless: false,
tryBeforeNotes: true,
shapes: true,
captures: true,
shareConversations: false,
agents: ["claude-code"],
bigChangeLines: 300,
};
export function withDefaults(settings: Partial<PanelSettings> | undefined): PanelSettings {
return { ...DEFAULT_SETTINGS, ...settings };
}
/** The keys `GET /api/config` returns; never the setup-time or security-adjacent ones. */
export function editableSettings(settings: PanelSettings): PanelEditableSettings {
return {
recorder: settings.recorder,
messageSummaries: settings.messageSummaries,
startupContext: settings.startupContext,
recordHeadless: settings.recordHeadless,
tryBeforeNotes: settings.tryBeforeNotes,
shapes: settings.shapes,
captures: settings.captures,
language: settings.language,
shareConversations: settings.shareConversations,
};
}
/** How a read-only value reads in the modal. */
export function formatSetting(value: PanelSettings[keyof PanelSettings] | undefined): string {
if (Array.isArray(value)) return value.length > 0 ? value.join(", ") : "—";
if (typeof value === "boolean") return value ? "yes" : "no";
return value === undefined ? "—" : String(value);
}