Unlike CLI tools where each invocation is stateless, sage.el follows REPL semantics:

1. Continuous Context: Your conversation accumulates naturally
2. Visual History: See previous exchanges in the *sage* buffer
3. Project Binding: Context is scoped to your project directory

• Buffer State: Conversations persist like any other buffer
• Mode Integration: Works with project.el, projectile, magit
• Org-mode: Export conversations, embed in documents
• Tool Extensibility: Write tools in Elisp, not shell scripts

Optional Integrations
├── sage-magit.el        # Git operations via Magit
└── sage-org.el          # Org-mode document support

Major features go through a formal RFC process:

1. Proposal: Write RFC document with motivation, design, alternatives
2. Multi-Stakeholder Review: L7 (API), CTO (Architecture), Developer, Release
3. Test Specification: Aggressive test plan before implementation
4. Implementation: Phased rollout with backward compatibility

See: RFC-SESSION-STORAGE.org

We use specialized "agent personas" for comprehensive code review:

All development tasks are tracked using beads (bd):

bd list              # See all open issues
bd ready             # Find unblocked work
bd create "Feature"  # Create new task
bd close <id>        # Complete task

Current bead: gemini-repl-010-5uh (Session Storage RFC)

;; Register a custom tool
(sage-tools-register
 "my-tool"
 :description "My custom tool"
 :parameters '((param1 . "string"))
 :handler #'my-tool-handler)

Built-in tools:

• read_file, write_file, edit_file
• bash (command execution)
• search_files, list_files
• project_info, buffer_info

Sessions are stored per-project with automatic continuation:

~/.emacs.d/sage/projects/<encoded-path>/
├── <session-uuid>.jsonl       # Session conversation
├── sessions.json              # Session index
└── history/                   # Archived sessions

Key behaviors:

• Auto-continue: Restart Emacs and pick up where you left off
• Project-scoped: Different projects maintain separate contexts
• Exportable: JSONL format compatible with other TCAs

(setq sage-ratelimit-requests-per-minute 60)
(setq sage-ratelimit-tokens-per-minute 100000)

Features:

• Token counting with cl-100k-base estimation
• Exponential backoff on 429 errors
• Request queue with priority

Automatic context window management:

(setq sage-context-max-tokens 128000)
(setq sage-context-reserve-output 4096)

• Automatic truncation when approaching limits
• Preservation of system prompts and recent messages
• Token usage reporting via /context command

sage.el follows the Tool Calling Agent (TCA) session schema for interoperability with other AI coding assistants:

{
  "uuid": "msg-uuid",
  "sessionId": "session-uuid",
  "role": "user|assistant|system|tool",
  "content": "message content",
  "timestamp": "2026-01-11T22:00:00Z",
  "tool_calls": [...]
}

Compatible with:

• Claude Code (~/.claude/projects/)
• Gemini CLI
• Future: Amp, Aider, Cursor

Tests: 99 passed, 0 failed
Modules tested:
- sage-test.el: 9/9 passed
- sage-context-test.el: 12/12 passed
- sage-emacs-test.el: 9/9 passed
- sage-memory-test.el: 18/18 passed
- sage-project-test.el: 18/18 passed
- sage-queue-test.el: 11/11 passed
- sage-ratelimit-test.el: 22/22 passed

Run tests:

make test-all          # Run all tests
make test-session      # Session-specific tests
make test-coverage     # With coverage report

GitHub Actions runs on every push:

• Byte compilation (Emacs 28.2, 29.4, 30.1)
• ERT test suite
• Checkdoc validation
• Package-lint compliance

• [X] Multi-provider support (Ollama, Gemini, OpenAI, Anthropic)
• [X] Tool calling framework
• [X] Session persistence
• [X] Rate limiting
• [X] Context management

• [X] Magit integration
• [X] Org-mode support
• [ ] Project.el deep integration
• [ ] Dired tool support

• [ ] Sub-agent spawning
• [ ] Cloud sync (optional)
• [ ] Voice input (whisper.el)
• [ ] Image understanding (multimodal)

• [ ] MELPA submission
• [ ] Emacs Wiki documentation
• [ ] Community tool repository