← All docs

DOCS

  1. Getting Started
  2. Configuration
  3. Tools
  4. Sessions
  5. Compaction & Branch Summarization
  6. Subagents
  7. Extensions
  8. Themes
  9. Memory System
  10. Skills
  11. Code intelligence (LSP)
  12. Termux Support
  13. Environment variables
  14. Custom Providers
  15. JSON Event Stream Mode
  16. Keybindings
  17. Prompt Templates
  18. RPC Mode
  19. Session File Format
  20. Shell Aliases
  21. Terminal Setup
  22. tmux Setup
DOCS
  1. Getting Started
  2. Configuration
  3. Tools
  4. Sessions
  5. Compaction & Branch Summarization
  6. Subagents
  7. Extensions
  8. Themes
  9. Memory System
  10. Skills
  11. Code intelligence (LSP)
  12. Termux Support
  13. Environment variables
  14. Custom Providers
  15. JSON Event Stream Mode
  16. Keybindings
  17. Prompt Templates
  18. RPC Mode
  19. Session File Format
  20. Shell Aliases
  21. Terminal Setup
  22. tmux Setup
ON THIS PAGE
  1. File Location
  2. Session Version
  3. Entry Types
  4. Header
  5. Message
  6. Compaction
  7. Branch Summary
  8. Custom (Extension)
  9. Label
  10. Thinking Level Change
  11. Model Change
  12. Session Info
  13. Content Blocks
  14. Message Types
  15. UserMessage
  16. AssistantMessage
  17. ToolResultMessage
  18. Extended Messages
  19. Tree Structure
  20. Deleting Sessions

Session File Format

Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with a type field. Entries form a tree structure via id/parentId fields, enabling in-place branching without creating new files.

#File Location

~/.neo-code/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl

Where <path> is the working directory with / replaced by -.

#Session Version

  • Version 1: Linear entry sequence (legacy, auto-migrated)
  • Version 2: Tree structure with id/parentId linking
  • Version 3: Current version

Existing sessions are automatically migrated to v3 when loaded.

#Entry Types

#Header

First entry in every session file (type field is "session"):

{"type":"session","version":3,"id":"...","timestamp":"2026-05-27T01:00:00.000Z","cwd":"/path/to/project"}

#Message

{"type":"message","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","message":{"role":"user","content":"hello","timestamp":1234567890}}

Message roles: user, assistant, toolResult, bashExecution, custom, branchSummary, compactionSummary

#Compaction

{"type":"compaction","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","summary":"...","firstKeptEntryId":"...","tokensBefore":50000,"details":{"readFiles":[],"modifiedFiles":[]}}

#Branch Summary

{"type":"branch_summary","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","summary":"...","fromId":"...","details":{"readFiles":[],"modifiedFiles":[]}}

#Custom (Extension)

{"type":"custom","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","customType":"my-extension","data":{"key":"value"}}

#Label

{"type":"label","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","targetId":"...","label":"checkpoint"}

#Thinking Level Change

{"type":"thinking_level_change","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","thinkingLevel":"high"}

#Model Change

{"type":"model_change","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","provider":"neosantara","modelId":"deepseek-v4-0324"}

#Session Info

{"type":"session_info","id":"...","parentId":"...","timestamp":"2026-05-27T01:00:00.000Z","name":"My Session"}

#Content Blocks

Messages contain typed content blocks:

// Text
{ type: "text", text: "..." }

// Image
{ type: "image", data: "base64...", mimeType: "image/png" }

// Thinking
{ type: "thinking", thinking: "..." }

// Tool Call
{ type: "toolCall", id: "...", name: "read", arguments: { path: "file.ts" } }

#Message Types

#UserMessage

{ role: "user", content: string | (TextContent | ImageContent)[], timestamp: number }

#AssistantMessage

{ role: "assistant", content: (TextContent | ThinkingContent | ToolCall)[], usage: Usage, stopReason: string, timestamp: number }

#ToolResultMessage

{ role: "toolResult", toolCallId: string, toolName: string, content: (TextContent | ImageContent)[], isError: boolean, timestamp: number }

#Extended Messages

  • BashExecutionMessage — user !/!! command results
  • CustomMessage — extension-injected messages (with customType and data)
  • BranchSummaryMessage — injected when navigating tree
  • CompactionSummaryMessage — injected after compaction

#Tree Structure

Entries link via id/parentId. Multiple children of the same parent create branches:

header (id: "a")
  └─ user msg (id: "b", parentId: "a")
       ├─ assistant msg (id: "c", parentId: "b")
       │    └─ tool result (id: "d", parentId: "c")
       └─ assistant msg (id: "e", parentId: "b")  ← branch

The active branch is the path from root to the current leaf. /tree navigates between branches.

#Deleting Sessions

Delete .jsonl files under ~/.neo-code/agent/sessions/, or use /resume and press Ctrl+D on a session to delete it interactively.

ON THIS PAGE

  1. File Location
  2. Session Version
  3. Entry Types
  4. Header
  5. Message
  6. Compaction
  7. Branch Summary
  8. Custom (Extension)
  9. Label
  10. Thinking Level Change
  11. Model Change
  12. Session Info
  13. Content Blocks
  14. Message Types
  15. UserMessage
  16. AssistantMessage
  17. ToolResultMessage
  18. Extended Messages
  19. Tree Structure
  20. Deleting Sessions
Previous← RPC ModeNextShell Aliases →

Neo Code

Neosantara-first AI coding agent for your terminal.

Product

  • Docs
  • Pricing
  • GitHub

Neosantara

  • Dashboard
  • API

Legal

  • Terms
  • Privacy

2026 Neosantara. All rights reserved.