DevScribe 📝

AI-powered terminal session logger — git log for your whole dev life

DevScribe silently watches your terminal sessions and builds a searchable, AI-summarized log. Get plain-English summaries of what you built, broke, and learned.

Features

🪝 Shell Hook - Captures every command with exit codes and timestamps
📁 Project Detection - Auto-tags sessions with git repo names
🤖 AI Summaries - Get 5-bullet session recaps powered by LiteLLM
🔍 Search - Fuzzy find through your entire command history
📊 Export - Generate markdown reports of your work
💻 Session Tracking - Start/stop sessions to organize your work

Quick Start

# Clone and install
git clone https://github.com/devscribe/devscribe.git
cd devscribe
./install.sh

# Start a session
devscribe start

# Work normally... your commands are being logged

# Get an AI summary
devscribe recap

# Search your history
devscribe search "docker"

# Export your work
devscribe export --last 7d -o weekly.md

Installation

Prerequisites

Python 3.12+
A supported shell (bash or zsh)

Install

# Clone the repository
git clone https://github.com/devscribe/devscribe.git
cd devscribe

# Run the installer
./install.sh

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

Manual Installation

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Install shell hook
devscribe install

Commands

Session Management

# Start a new session (auto-detects project from git repo)
devscribe start

# Start with explicit project name
devscribe start my-project

# End current session
devscribe stop

# Show session status
devscribe status

AI Features

# Get AI summary of current/last session
devscribe recap

# Get summary of all today's sessions
devscribe recap --today

# Explain a failed command
devscribe recap --explain <command-id>

Search & List

# List recent sessions
devscribe list

# List today's sessions
devscribe list --today

# List sessions from last 3 days
devscribe list --last 3

# Filter by project
devscribe list --project my-app

# Search commands
devscribe search "npm install"

# Interactive search with fzf
devscribe search "error" --interactive

# List recent commands
devscribe list-commands

# Show only failed commands
devscribe list-commands --failed

Export

# Export last 7 days (default)
devscribe export

# Export last 30 days
devscribe export --last 30

# Export today only
devscribe export --today

# Export specific project
devscribe export --project my-app

# Export as shell script (successful commands only)
devscribe export --script -o setup.sh

Configuration

# View all config
devscribe config --list

# Set AI model
devscribe config ai_model zai/glm-4

# Disable AI
devscribe config ai_enabled false

Utilities

# List all projects
devscribe projects

# Clean up old sessions
devscribe cleanup --days 30

# Install shell hook
devscribe install

# Uninstall shell hook
devscribe uninstall

AI Configuration

DevScribe uses LiteLLM for model-agnostic AI calls.

Supported Models

Set your preferred model with:

devscribe config ai_model <model_name>

Common options:

zai/glm-4 - GLM-4 via ZhipuAI (default)
gpt-4 - OpenAI GPT-4
gpt-3.5-turbo - OpenAI GPT-3.5
claude-3-opus-20240229 - Anthropic Claude

API Keys

Set the appropriate environment variable:

# For ZhipuAI (default)
export ZHIPUAI_API_KEY=your_key_here

# For OpenAI
export OPENAI_API_KEY=your_key_here

# For Anthropic
export ANTHROPIC_API_KEY=your_key_here

Add to your ~/.bashrc or ~/.zshrc to persist.

Database

DevScribe stores data in SQLite at ~/.devscribe/devscribe.db.

Schema

CREATE TABLE sessions (
    id INTEGER PRIMARY KEY,
    started_at TIMESTAMP,
    ended_at TIMESTAMP,
    project TEXT,
    summary TEXT,
    is_active BOOLEAN
);

CREATE TABLE commands (
    id INTEGER PRIMARY KEY,
    session_id INTEGER,
    command TEXT,
    exit_code INTEGER,
    timestamp TIMESTAMP,
    working_dir TEXT,
    FOREIGN KEY (session_id) REFERENCES sessions(id)
);

Configuration File

Location: ~/.devscribe/config.json

Default settings:

{
    "ai_model": "zai/glm-4",
    "ai_enabled": true,
    "auto_summarize": false,
    "max_commands_per_summary": 100,
    "export_format": "markdown"
}

Shell Integration

DevScribe uses PROMPT_COMMAND (bash) or precmd hooks (zsh) to capture commands.

How It Works

After each command, the hook captures:
- The command text (from history)
- Exit code
- Working directory
- Timestamp
This data is sent to devscribe log in the background
Commands are associated with the active session

Manual Hook Installation

If the automatic installation doesn't work, add this to your ~/.bashrc:

# DevScribe hook
export PROMPT_COMMAND='devscribe log "$(history 1 | sed "s/^[ ]*[0-9]*[ ]*//")" "$?" "$PWD" 2>/dev/null; '"$PROMPT_COMMAND"

For zsh (~/.zshrc):

# DevScribe hook
_devscribe_precmd() {
    devscribe log "$(history -1 | sed 's/^[ ]*[0-9]*[ ]*//')" "$?" "$PWD" 2>/dev/null
}
autoload -Uz add-zsh-hook
add-zsh-hook precmd _devscribe_precmd

Examples

Daily Workflow

# Morning: start a session
devscribe start

# Work on your project...
npm install
npm run dev
git checkout -b feature/new-ui
# ... commands are being logged ...

# End of day: get a summary
devscribe stop
devscribe recap

# Export your work
devscribe export --today -o daily-standup.md

Weekly Review

# Export the week's work
devscribe export --last 7 -o weekly-report.md

# List all projects you worked on
devscribe projects

Debugging Session

# Search for error-related commands
devscribe search "error" --interactive

# List failed commands
devscribe list-commands --failed

# Get AI explanation of a failure
devscribe recap --explain 123

Development

Setup

# Clone and setup dev environment
git clone https://github.com/devscribe/devscribe.git
cd devscribe
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Project Structure

devscribe/
├── __init__.py    # Package init, paths
├── cli.py         # Typer CLI commands
├── db.py          # Peewee models, DB ops
├── ai.py          # LiteLLM integration
├── hook.py        # Shell hook generation
└── export.py      # Markdown export

Running Tests

pytest tests/

Graceful Degradation

DevScribe works without AI:

All core logging features work without API keys
AI commands (recap, explain) will show a helpful message
Search, list, and export work normally

Privacy

All data is stored locally in ~/.devscribe/
No telemetry or external calls (except AI if configured)
You control what gets exported

Troubleshooting

Commands not being logged

Check if hook is installed:
```
devscribe install
```
Reload your shell:
```
source ~/.bashrc
```
Check for active session:
```
devscribe status
```

AI not working

Check API key is set:
```
echo $ZHIPUAI_API_KEY
```
Verify AI is enabled:
```
devscribe config ai_enabled
```

Database issues

The database is at ~/.devscribe/devscribe.db. You can:

Back it up: cp ~/.devscribe/devscribe.db ~/backup/
Delete it to start fresh: rm ~/.devscribe/devscribe.db

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Acknowledgments

Typer - CLI framework
Rich - Beautiful terminal output
Peewee - Simple ORM
LiteLLM - Model-agnostic AI

Made with ❤️ for developers who forget what they did yesterday

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
devscribe		devscribe
docs		docs
tests		tests
.gitignore		.gitignore
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation