SessionDocGen v1.0

Auto-Generate Session Summaries from Tool Usage, Decisions, and Outcomes

Turn verbose session logs into clear, actionable documentation automatically. SessionDocGen analyzes tool calls, tracks file modifications, extracts decisions, and generates comprehensive reports - reducing manual documentation time by 90%.

What It Does

Problem: Long coding sessions generate thousands of tool calls and decisions, but creating session documentation requires manual work - reviewing logs, counting metrics, summarizing outcomes. IRIS reported a 52,000-word manual documentation burden from a single 3.5-hour session.

Solution: SessionDocGen automates session documentation by:

Extracting tool usage statistics (type, count, percentage)
Identifying error->solution patterns
Tracking file modifications (created, edited, deleted with diffs)
Capturing key decisions and their rationale
Generating timeline of milestones
Summarizing outcomes (working features, bugs found, pending items)
Calculating metrics (duration, LOC written, files touched)

Real Impact:

# BEFORE: Manual documentation after a 3.5-hour session
# - Review 100+ tool calls manually
# - Count files modified by hand
# - Summarize decisions from memory
# - Time: 40+ minutes
# - Accuracy: Incomplete, subjective

# AFTER: SessionDocGen
from sessiondocgen import SessionDocGen
gen = SessionDocGen()
gen.load_log_file("session.log")
gen.save_report("summary.md", format="markdown")
# Time: < 5 seconds
# Accuracy: Complete, objective, reproducible

# SAVED: 40 minutes per session

Quick Start

Installation

# Clone or download
git clone https://github.com/DonkRonk17/SessionDocGen.git
cd SessionDocGen

# Run immediately (no dependencies required!)
python sessiondocgen.py --help

# OR install for global access
pip install -e .

Requirements: Python 3.8+ (standard library only - no pip install needed!)

Basic Usage

# Parse a log file and generate markdown report
python sessiondocgen.py parse session.log -o summary.md

# Quick summary to stdout
python sessiondocgen.py summary session.log

# Generate JSON report
python sessiondocgen.py parse session.log -f json -o summary.json

# Show tool usage statistics
python sessiondocgen.py stats session.log

Usage

Command Line Interface

# Parse single log file
python sessiondocgen.py parse session.log -o report.md

# Parse multiple log files (combined)
python sessiondocgen.py parse day1.log day2.log day3.log -o weekly.md

# Specify session name
python sessiondocgen.py parse session.log -n "Feature Implementation" -o report.md

# Include git diff for file modifications
python sessiondocgen.py parse session.log --git-diff changes.diff -o report.md

# Output formats
python sessiondocgen.py parse session.log -f markdown -o report.md  # Default
python sessiondocgen.py parse session.log -f json -o report.json
python sessiondocgen.py parse session.log -f text -o report.txt

# Verbose mode
python sessiondocgen.py parse session.log -v -o report.md

All Options:

sessiondocgen parse [logs...] [options]
  logs              Log files to parse (one or more)
  -o, --output      Output file path
  -f, --format      Output format: markdown, json, text (default: markdown)
  -n, --name        Session name (default: "Session")
  --git-diff        Git diff file for file modification details
  -v, --verbose     Verbose output

sessiondocgen summary [logs...]
  logs              Log files to parse
  -n, --name        Session name

sessiondocgen stats [logs...]
  logs              Log files to analyze

sessiondocgen milestone <title> [options]
  title             Milestone title
  -d, --description Milestone description
  -i, --impact      Impact level: minor, major, critical
  -r, --report      JSON report file to update (required)

Python API

from sessiondocgen import SessionDocGen

# Initialize
gen = SessionDocGen()

# Load from log file
gen.load_log_file("session.log")

# Or load from string content
gen.load_content("""
<invoke name="read_file">
<parameter name="target_file">main.py</parameter>
</invoke>
""")

# Add git diff for detailed file modifications
with open("changes.diff", "r") as f:
    gen.load_git_diff(f.read())

# Set session metadata
gen.session_name = "Feature Implementation"
gen.start_time = datetime(2026, 1, 25, 10, 0, 0)
gen.end_time = datetime(2026, 1, 25, 14, 30, 0)

# Add manual annotations
gen.add_milestone("MVP Complete", "All core features working", "major")
gen.add_decision("Use SQLite", "architecture", "Zero dependencies")
gen.add_error_solution(
    "ModuleNotFoundError: No module named 'requests'",
    "dependency",
    "pip install requests",
    effective=True
)

# Generate reports
md_report = gen.generate_report("markdown", "Feature Session")
json_report = gen.generate_report("json")
text_report = gen.generate_report("text")

# Save to file
gen.save_report("summary.md", format="markdown", session_name="Feature Session")

# Get quick summary
summary = gen.get_summary()
print(f"Tool calls: {summary['tool_calls']}")
print(f"Files touched: {summary['files_touched']}")
print(f"Errors: {summary['errors']} ({summary['errors_resolved']} resolved)")

# Reset for new session
gen.reset()

Real-World Results

Test: Analyzing a Complex Session

Input: 3.5-hour coding session log with 100+ tool calls

$ python sessiondocgen.py parse complex_session.log -o summary.md

Report saved to: summary.md

Generated Report Excerpt:

# Complex Session Summary

**Generated:** 2026-01-25 14:30:00
**Duration:** 210.5 minutes

## Quick Stats

| Metric | Value |
|--------|-------|
| Total Tool Calls | 127 |
| Successful | 119 |
| Files Created | 8 |
| Files Edited | 23 |
| Lines Added | 2,847 |
| Lines Removed | 412 |
| Errors Encountered | 6 |
| Errors Resolved | 6 |
| Decisions Made | 14 |
| Milestones | 5 |

## Tool Usage Breakdown

| Category | Count | Percentage |
|----------|-------|------------|
| write | 45 | 35.4% |
| read | 38 | 29.9% |
| search | 22 | 17.3% |
| terminal | 15 | 11.8% |
| other | 7 | 5.5% |

Time Savings:

Manual documentation: ~40 minutes
SessionDocGen: ~5 seconds
Saved: 39+ minutes per session

Report Formats

Markdown Report

Professional, readable format ideal for:

GitHub READMEs and wikis
Team documentation
Session handoffs
Archive records

Features:

Quick stats table
Tool usage breakdown with percentages
File modifications list
Error/solution pairs with status
Key decisions by category
Milestones timeline
ASCII timeline visualization

JSON Report

Structured data format ideal for:

Automated processing
Database storage
API integration
Custom reporting

Structure:

{
  "session_name": "Feature Implementation",
  "generated_at": "2026-01-25T14:30:00",
  "metrics": {
    "duration_minutes": 210.5,
    "total_tool_calls": 127,
    "successful_tool_calls": 119,
    "files_created": 8,
    "files_edited": 23,
    "total_lines_added": 2847,
    "total_lines_removed": 412
  },
  "tool_usages": [...],
  "file_modifications": [...],
  "errors": [...],
  "decisions": [...],
  "milestones": [...]
}

Text Report

Plain text format ideal for:

Terminal output
Email attachments
Systems without markdown support
Quick reference

Supported Log Formats

SessionDocGen parses various log formats:

antml Invoke Format (Primary)

<invoke name="read_file">
<parameter name="target_file">main.py</parameter>
</invoke>

JSON Tool Calls

{"tool": "write", "args": {"file_path": "output.py"}}

Function Call Format

read_file(target_file="main.py")
write(file_path="output.py", contents="...")

Error Formats Detected

Python tracebacks
Build errors (Gradle, npm, webpack)
Exit codes (non-zero)
Generic error/failed messages

Tool Categories

SessionDocGen automatically categorizes tool calls:

Category	Tools
read	read_file, list_dir
write	write, search_replace, edit_notebook, delete_file
search	grep, glob_file_search, codebase_search
terminal	run_terminal_cmd
browser	browser_navigate, browser_snapshot, browser_click, browser_type
web	web_search
planning	todo_write
memory	update_memory
other	Uncategorized tools

Error Detection & Categorization

SessionDocGen automatically detects and categorizes errors:

Type	Detection Patterns
dependency	import, module, package, pip
syntax	syntax, parse, unexpected token, indent
build	build, compile, gradle, npm run, webpack
network	network, connection, timeout, socket, http
permission	permission, access denied, unauthorized
runtime	Default for unmatched errors

Decision Detection

SessionDocGen identifies decisions using keyword patterns:

Trigger Keywords:

decided, decision, chose, choosing, selected
opted, went with, will use, using
implemented, implementing, approach, strategy, solution

Categories:

architecture: design, structure, pattern, module
bug_fix: fix, bug, error, issue, problem, resolve
optimization: optimize, performance, speed, efficient, cache
handoff: handoff, transition, switch, pass to
config: config, configuration, setting, environment, variable

Dependencies

SessionDocGen uses only Python's standard library:

os - File system operations
sys - System interface
json - JSON parsing/generation
re - Regular expressions
argparse - CLI argument parsing
datetime - Time handling
typing - Type hints
collections - defaultdict
dataclasses - Data structures
pathlib - Path handling
hashlib - Hashing

No pip install required!

How It Works

Multi-Stage Processing Pipeline

Log Parsing: Extract tool calls, errors, and raw content
File Modification Tracking: Identify created/edited/deleted files
Decision Extraction: Find and categorize decisions
Metrics Calculation: Aggregate counts, durations, statistics
Report Generation: Format data into markdown/JSON/text

Tool Usage Parser

# Parses antml invoke format
content = '<invoke name="read_file"></invoke>'
parser = ToolUsageParser()
usages, errors = parser.parse_content(content)
# usages[0].tool_name == "read_file"
# usages[0].category == "read"

File Modification Parser

# Extracts from tool usages
usages = [ToolUsage(tool_name="write", arguments={"file_path": "new.py"})]
parser = FileModificationParser()
mods = parser.parse_from_tool_usages(usages)
# mods[0].file_path == "new.py"
# mods[0].modification_type == "created"

# Or from git diff
mods = parser.parse_from_git_diff(diff_content)
# Includes lines_added, lines_removed

Metrics Calculator

calculator = MetricsCalculator()
metrics = calculator.calculate(
    tool_usages,
    file_modifications,
    errors,
    decisions,
    milestones,
    start_time,
    end_time
)
# metrics.total_tool_calls, metrics.unique_files_touched, etc.

Use Cases

For AI Developers

# After a coding session, generate documentation
from sessiondocgen import SessionDocGen

gen = SessionDocGen()
gen.load_log_file("cursor_session.log")
gen.session_name = "Feature: User Authentication"
gen.add_milestone("Login Working", "Users can log in", "major")
gen.save_report("docs/auth_session.md")

For Team Leads

# Combine daily logs into weekly report
gen = SessionDocGen()
gen.session_name = "Week 4 Summary"

for day in ["mon.log", "tue.log", "wed.log", "thu.log", "fri.log"]:
    gen.load_log_file(f"logs/{day}")

gen.save_report("weekly_summary.md")
summary = gen.get_summary()
print(f"Week Total: {summary['tool_calls']} tool calls")

For Documentation Automation

# CI/CD integration
python sessiondocgen.py parse $SESSION_LOG \
    -n "Build #$BUILD_NUMBER" \
    -f json \
    -o artifacts/session_report.json

For Error Pattern Analysis

# Find error patterns across sessions
gen = SessionDocGen()
for log in glob.glob("sessions/*.log"):
    gen.load_log_file(log)

report = gen.generate_report("json")
data = json.loads(report)

# Analyze error distribution
error_types = Counter(e["error_type"] for e in data["errors"])
print("Most common errors:", error_types.most_common(5))

Integration with Team Brain

With ContextPreserver

from sessiondocgen import SessionDocGen
from contextpreserver import ContextPreserver

# Generate session summary
gen = SessionDocGen()
gen.load_log_file("session.log")
summary = gen.get_summary()

# Store in context preserver
preserver = ContextPreserver()
preserver.add_event(
    "SESSION_SUMMARY",
    f"Session completed: {summary['tool_calls']} tools, "
    f"{summary['files_touched']} files modified"
)

With PostMortem

from sessiondocgen import SessionDocGen

# SessionDocGen provides the data, PostMortem analyzes patterns
gen = SessionDocGen()
gen.load_log_file("session.log")

# Export for PostMortem analysis
gen.save_report("session_data.json", format="json")

# PostMortem can then analyze error patterns, decision outcomes, etc.

With SynapseLink

from sessiondocgen import SessionDocGen
from synapselink import quick_send

gen = SessionDocGen()
gen.load_log_file("session.log")
summary = gen.get_summary()

# Notify team of session completion
quick_send(
    "FORGE,CLIO,NEXUS",
    "Session Complete",
    f"Tools: {summary['tool_calls']}, Files: {summary['files_touched']}, "
    f"Errors: {summary['errors']} ({summary['errors_resolved']} resolved)"
)

Statistics Command

Get detailed tool usage statistics:

$ python sessiondocgen.py stats session.log

=== Tool Usage Statistics ===

By Category:
----------------------------------------
  write          45 ( 35.4%) ###########
  read           38 ( 29.9%) #########
  search         22 ( 17.3%) #####
  terminal       15 ( 11.8%) ###
  other           7 (  5.5%) #

Top 10 Tools:
----------------------------------------
  write                               45 ( 35.4%)
  read_file                           28 ( 22.0%)
  grep                                15 ( 11.8%)
  search_replace                      12 (  9.4%)
  run_terminal_cmd                    10 (  7.9%)
  list_dir                             8 (  6.3%)
  codebase_search                      5 (  3.9%)
  delete_file                          3 (  2.4%)
  web_search                           1 (  0.8%)

Total Tool Calls: 127

Troubleshooting

Issue: No tool calls detected

Cause: Log format not recognized Fix: Ensure logs contain antml invoke format or supported patterns:

<invoke name="tool_name">...</invoke>

Issue: Empty file modifications

Cause: Tool usages don't include write operations Fix: Either:

Ensure write/search_replace/delete_file calls are in logs
Provide git diff with --git-diff option

Issue: Decision extraction missing items

Cause: Decisions not using trigger keywords Fix: Use explicit decision keywords:

"We decided to..."
"I chose to..."
"The solution is..."

Still Having Issues?

Check EXAMPLES.md for working examples
Review CHEAT_SHEET.txt for quick reference
Ask in Team Brain Synapse
Open an issue on GitHub

Documentation

EXAMPLES.md - 10+ working examples
CHEAT_SHEET.txt - Quick reference
INTEGRATION_PLAN.md - Integration guide
QUICK_START_GUIDES.md - Agent-specific guides

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run tests (python -m pytest test_sessiondocgen.py -v)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE for details.

Credits

Built by: ATLAS (Team Brain)
Requested by: IRIS (Tool Request #21 - needed to reduce 52,000-word manual documentation burden)
For: Randell Logan Smith / Metaphy LLC
Part of: Beacon HQ / Team Brain Ecosystem
Date: January 25, 2026
Methodology: Holy Grail Protocol (83/83 tests passing)

Built with care as part of the Team Brain ecosystem - where AI agents collaborate to solve real problems.

Links

GitHub: https://github.com/DonkRonk17/SessionDocGen
Issues: https://github.com/DonkRonk17/SessionDocGen/issues
Author: https://github.com/DonkRonk17
Company: Metaphy LLC
Ecosystem: Part of HMSS (Heavenly Morning Star System)

Quick Reference

# Parse and generate report
python sessiondocgen.py parse session.log -o summary.md

# Quick summary
python sessiondocgen.py summary session.log

# Tool statistics
python sessiondocgen.py stats session.log

# JSON output
python sessiondocgen.py parse session.log -f json -o data.json

# Multiple logs
python sessiondocgen.py parse *.log -o combined.md

# With git diff
python sessiondocgen.py parse session.log --git-diff changes.diff -o report.md

# Add milestone to existing report
python sessiondocgen.py milestone "Feature Complete" -r report.json

SessionDocGen - Turn session chaos into clear documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
branding		branding
.gitignore		.gitignore
CHEAT_SHEET.txt		CHEAT_SHEET.txt
EXAMPLES.md		EXAMPLES.md
INTEGRATION_EXAMPLES.md		INTEGRATION_EXAMPLES.md
INTEGRATION_PLAN.md		INTEGRATION_PLAN.md
LICENSE		LICENSE
QUICK_START_GUIDES.md		QUICK_START_GUIDES.md
README.md		README.md
requirements.txt		requirements.txt
sessiondocgen.py		sessiondocgen.py
setup.py		setup.py
test_sessiondocgen.py		test_sessiondocgen.py

License

DonkRonk17/SessionDocGen

Folders and files

Latest commit

History

Repository files navigation

SessionDocGen v1.0

What It Does

Quick Start

Installation

Basic Usage

Usage

Command Line Interface

Python API

Real-World Results

Test: Analyzing a Complex Session

Report Formats

Markdown Report

JSON Report

Text Report

Supported Log Formats

antml Invoke Format (Primary)

JSON Tool Calls

Function Call Format

Error Formats Detected

Tool Categories

Error Detection & Categorization

Decision Detection

Dependencies

How It Works

Multi-Stage Processing Pipeline

Tool Usage Parser

File Modification Parser

Metrics Calculator

Use Cases

For AI Developers

For Team Leads

For Documentation Automation

For Error Pattern Analysis

Integration with Team Brain

With ContextPreserver

With PostMortem

With SynapseLink

Statistics Command

Troubleshooting

Issue: No tool calls detected

Issue: Empty file modifications

Issue: Decision extraction missing items

Still Having Issues?

Documentation

Contributing

License

Credits

Links

Quick Reference

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages