---

⚡ TerminalPulse

Short-term memory for AI agents. Captures your coding context in real time — silently.

Detect errors, track your focus, and fix bugs instantly — no copy-pasting, no explaining, no context switching. TerminalPulse watches your terminal, editor, and filesystem. When something breaks, it already knows what happened.

---

             

---

📋 Table of Contents

• The Problem
• The Solution
• How It Works
• Installation
• Setup
• Commands
• Real World Scenarios
• Auto-Suggest on Error
• MCP Integration
• Language & Project Support
• The Difference
• Security & Privacy
• Requirements
• Tests
• Contributing
• License

---

🔥 The Problem Every Developer Knows

You're deep in a feature. Your build breaks. Now you have to:

1. Read the traceback
2. Copy the error
3. Switch to Claude / ChatGPT / Cursor
4. Explain your project, your git branch, which file you were editing
5. Paste the file contents
6. Wait for the answer
7. Switch back to terminal
8. Apply the fix manually

That's 2 minutes of context-switching friction. Every. Single. Time.

The worst part? The AI doesn't know anything about what you were doing. You have to re-explain everything from scratch.

---

✅ The Solution

# Your Next.js build breaks at 2am
npm run build
# TypeError: Cannot read properties of undefined (reading 'userId')
# ⚡ Error detected. Run 'pulse fix' to auto-fix.

pulse fix
# TerminalMind already knows:
# → Project: Next.js + TypeScript
# → Branch: feature/auth
# → Last commit: "add JWT middleware"
# → Active file: src/middleware/auth.ts
# → Full build error output
# → Actual file contents
# → Precise fix in seconds

No switching tabs. No explaining. No copy-pasting.

---

🏗️ How It Works

Three silent streams feed a time-decaying knowledge graph:

Stream	Source	What It Captures
Focus	VS Code window title	Which file is active in your editor
Activity	Filesystem watchdog	Which files were just saved
Distress	Bash hook	Which terminal commands just failed

Every event gets a heat score that decays over time:

heat = e^(-λ × seconds_since_event) × severity

Older events fade automatically. The AI always gets what's relevant right now — not noise from this morning's work.

Data Flow

VS Code (Windows) → HTTP:7077  ─┐
Terminal errors   → Unix socket ─┼→ pulsed daemon → ~/.devpulse_state.json
File saves        → watchdog   ─┘                         ↓
                                          pulse fix → TerminalMind → Fix

Technology Stack

Layer	Technology	Role
Daemon	Python asyncio	Long-lived background process
Graph	NetworkX + Pydantic	Time-decaying knowledge graph
CLI	Typer + Rich	Commands and formatted output
AI Bridge	TerminalMind	Auto-fix powered by live context

---

🚀 Installation

pip install terminalpulse
pip install terminalmind
tmind auth

---

⚙️ Setup (One Time)

# Install system dependencies
pulse install-deps

# Inject shell hook
pulse init
source ~/.bashrc

# Start watching your project
cd your-project
pulse watch

That's it. TerminalPulse runs silently in the background from now on.

---

🛠️ Commands

Command	What It Does
pulse watch	Auto-detect project type and start daemon
pulse fix	Send full context to AI — no input needed
pulse context	Copy formatted context block for any AI
pulse summary	Plain English summary of your coding session
pulse insights	Detect recurring failure patterns
pulse report	End of day coding summary
pulse history	30-minute activity timeline
pulse state	Show raw JSON context
pulse init	Inject shell hook into .bashrc
pulse install-deps	Install system dependencies
pulse mcp	Start MCP server for Claude Desktop / Cursor
pulse_run <cmd>	Capture full stderr for large builds

---

🧑‍💻 Real World Scenarios

Scenario 1 — Full-Stack Developer (Next.js + TypeScript)

cd ~/my-saas
pulse watch
# Project detected: Next.js + TypeScript
# Watching: /home/user/my-saas

# Later — build breaks
npm run build
# Module not found: Can't resolve '@/components/AuthGuard'
# ⚡ Error detected. Run 'pulse fix' to auto-fix.

pulse fix
# Sends to TerminalMind:
# → Project: Next.js + TypeScript
# → Branch: feature/dashboard
# → Changed files: components/AuthGuard.tsx, pages/dashboard.tsx
# → Full webpack error
# → File contents of dashboard.tsx
# → Precise fix instantly

---

Scenario 2 — Backend Developer (Python / FastAPI)

cd ~/api-server
pulse watch
# Project detected: Python

# Server crashes
python3 main.py
# sqlalchemy.exc.OperationalError: no such table: users
# ⚡ Error detected. Run 'pulse fix' to auto-fix.

pulse fix
# AI knows you just edited models.py and ran a migration
# Gives exact Alembic fix, not a generic answer

---

Scenario 3 — You Use Claude, Not TerminalMind

pulse context
# Copies to clipboard:
# === TerminalPulse Context ===
# Project:      React + TypeScript
# Branch:       fix/payment-flow
# Active file:  src/checkout/PaymentForm.tsx
# Last error:   npm run build (exit 1)
# Changed files: PaymentForm.tsx, useStripe.ts
# File contents: [actual code]
# =============================

# Paste into Claude — full context in one paste

---

Scenario 4 — Recurring Bug Pattern

# After hitting the same error 4 times today
pulse insights

# ⚡ TerminalPulse Insights
# Project: Python | Branch: feature/auth
#
# Recurring failure: python3 server.py failed 4 times
# → All failures occurred after editing config.py
# → Suggestion: run pulse fix to investigate root cause
# High error rate: 80%
# → Consider adding input validation to config.py

---

Scenario 5 — End of Day Standup

pulse report

# 📊 TerminalPulse Daily Report
# Branch: feature/payment-integration
#
# • Files saved:      23
# • Errors hit:        6
# • Focus changes:    14
#
# Most edited file:   PaymentForm.tsx (6 saves)
# Most common error:  npm run build (4x)
#
# Rough session — 6 errors. Run pulse insights for patterns.

---

Scenario 6 — Quick Session Summary

pulse summary

# 📝 Session Summary
#
# You are working on a Python project on branch feature/auth.
# Most of your time was spent editing models.py (6 saves).
# Your active file right now is models.py.
# You hit 3 errors, most from python3 server.py (3x).
# Last commit: add user authentication

Useful when coming back after a break — instant context of where you left off.

# Real output example:
(terminalpulse) prajwal@Prajwal:~/terminalpulse$ pulse summary

📝 Session Summary

You are on branch master.
Most of your time was spent editing cli.py (1 save).
You hit 1 error(s) this session.
Last commit: v0.5.0 - graceful fallback, pulse context, auto-suggest, install-deps

---

⚡ Auto-Suggest on Error

Every time a command fails, TerminalPulse prints:

⚡ Error detected. Run 'pulse fix' to auto-fix.

You never have to remember to use it.

---

🔌 MCP Integration (Claude Desktop / Cursor)

pulse mcp

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "terminalpulse": {
      "command": "pulse",
      "args": ["mcp"]
    }
  }
}

Claude Desktop now has live access to your coding context. Ask it:

• "What was I working on?"
• "What errors did I hit today?"
• "Which file is causing the most problems?"

Available tools:

Tool	Returns
get_pulse_state	Full current coding context
get_hottest_error	Most recent error with full stderr
get_active_context	Active file, language, git branch
get_history	Last 30 minutes timeline

---

🌍 Language & Project Support

Stack	Detection	Error Capture	Fix
Python / FastAPI / Django	✓	✓	✓
React / Next.js	✓	✓	✓
TypeScript / Node.js	✓	✓	✓
Rust	✓	✓	✓
Go	✓	✓	✓
Java / Spring	✓	✓	✓
Large builds (webpack, gradle, pytest)	✓ via pulse_run	✓	✓

---

📊 The Difference

Without TerminalPulse	With TerminalPulse
Copy error manually	Auto-captured
Switch to AI chat	Already connected
Explain your project	Auto-detected
Explain git branch	Auto-detected
Paste file contents	Auto-read
Wait for response	Instant
Apply fix manually	One keypress
~2 minutes every time	~5 seconds

---

🛡️ Security & Privacy

• Local first — your context graph lives entirely on your machine
• No telemetry — nothing is sent anywhere without your command
• Targeted context — only the specific error and active file go to the AI
• Secure keys — API keys stored in OS keyring, never in plain files

---

📋 Requirements

• Python 3.10+
• WSL Ubuntu (Linux daemon)
• netcat — pre-installed on Ubuntu
• terminalmind — for pulse fix
• Windows 11 + VS Code — for focus tracking (optional)

---

🧪 Tests

29 unit tests — all passing.

.venv/bin/pytest tests/ -v
# 29 passed in 0.83s

Category	Tests	What's Verified
Event model	4	COMMAND_FAILED, FILE_SAVED, FOCUS_CHANGED, COMMAND_OK — correct fields & timestamps
Language detection	8	.py → python, .ts → typescript, .tsx → typescript, .js → javascript, .rs → rust, .go → go, unknown ext, None input
Project type detection	8	pyproject.toml → python, requirements.txt → python, package.json → react-typescript / nextjs / node, Cargo.toml → rust, go.mod → go, empty folder → unknown
PulseGraph	9	Events added to graph, heat scores 0–1, errors linked to active file, hottest events sorted by heat, state written to disk, history recorded

---

🤝 Contributing

1. Fork the repository
2. Create your branch: git checkout -b feature/your-feature
3. Add tests for your feature — all PRs must include new tests covering new behaviour
4. Ensure all 29 existing tests still pass: .venv/bin/pytest tests/ -v
5. Commit: git commit -m 'Add your feature'
6. Push: git push origin feature/your-feature
7. Open a Pull Request

PRs without passing tests will not be merged.

---

📝 Changelog

Version	What's New
v0.5.0	pulse summary, graceful fallback, pulse context, auto-suggest on every error, pulse install-deps, 29 unit tests, demo screenshots
v0.4.0	MCP integration for Claude Desktop / Cursor
v0.3.0	pulse insights, pulse report, pattern detection
v0.2.0	pulse fix, TerminalMind bridge, Unix socket daemon
v0.1.0	Initial release — shell hook, file watcher, heat graph

---

📄 License

MIT © 2026 Prajwal Hulle — See LICENSE for full details.

---

Built for developers who are tired of copy-pasting errors into AI.