ctxstack

Documentation

Overview

Package ctxstack reports the effective instruction stack for a session: what is (or would be) loaded for a given cwd — the memory-file chain, hooks, and configured MCP servers — each with an estimated token cost, plus the live window/context figures and the session's compaction events. Read-only, no network. Token costs are estimates (~chars/4) and marked as such; the model window and current context are exact when the transcript recorded usage.

Index

• Constants
• func Compactions(path string) []int64
• func JSON(s Stack) ([]byte, error)
• type Layer
  • func Inventory(home, cwd string) (chain, hooks []Layer, chainTokens int, mcp []string)
• type Stack

Constants

const SchemaVersion = 1

SchemaVersion is the --json contract version for `agentdash context`.

Functions

func Compactions

func Compactions(path string) []int64

Compactions returns the epoch timestamps of context-compaction events in a Claude transcript (type "summary" entries — "the agent's memory was compacted at T"). Entries without a parseable timestamp are counted as a zero so the caller still sees the event happened.

func JSON

func JSON(s Stack) ([]byte, error)

JSON renders a Stack as the schema_version 1 context document.

Types

type Layer

type Layer struct {
	Kind    string `json:"kind"`  // instruction | rule | hook
	Scope   string `json:"scope"` // global | project | parent
	Path    string `json:"path"`
	Summary string `json:"summary,omitempty"`
	Tokens  int    `json:"tokens"` // estimated (~chars/4); 0 for hooks
}

Layer is one thing loaded into the context, with its estimated token cost.

func Inventory

func Inventory(home, cwd string) (chain, hooks []Layer, chainTokens int, mcp []string)

Inventory builds the static part of the stack (what config says would load for this cwd): the instruction/rule chain and hooks with estimated token costs, plus the configured MCP server names. Reuses config.Scan so the token estimates match `agentdash inspect`.

type Stack

type Stack struct {
	PID          int      `json:"pid"`
	Agent        string   `json:"agent"`
	Cwd          string   `json:"cwd"`
	Model        string   `json:"model"`
	WindowTokens int64    `json:"window_tokens"` // model context window (0 if unknown)
	CtxTokens    int64    `json:"ctx_tokens"`    // current context used (exact, from usage)
	CtxPct       int      `json:"ctx_pct"`
	ChainTokens  int      `json:"chain_tokens"` // estimated always-loaded instruction+rule total
	Chain        []Layer  `json:"chain"`
	Hooks        []Layer  `json:"hooks"`
	MCPServers   []string `json:"mcp_servers"`
	MCPTaxNote   string   `json:"mcp_tax_note"` // MCP tool-schema cost note (usually not measurable)
	Compactions  []int64  `json:"compactions"`  // epoch timestamps of compaction/summary events
}

Stack is the effective instruction stack for a session.