copilot-emacs — Emacs as AI Operating System

An AI-native personal operating system built on Emacs and GitHub Copilot. Every Emacs subsystem is a tool the agent can call. All data is plain text. The system is self-modifying — Lisp macros all the way down.

Built on copilot-sdk-elisp (ACP client library).

Features

Core — Chat UI & Built-in Tools

Interactive chat (copilot-chat.el) with streaming responses, markdown rendering, tool execution display, and mode-line state (🤖 idle | ⚡ thinking | 📝 streaming | 🔧 running tool). Header-line shows current model, reasoning effort, and summaries status.

14 built-in tools (copilot-emacs-tools.el):

Tool	What It Does
emacs-buffer-read	Read any open buffer
emacs-buffer-edit	Search-and-replace in a buffer (with diff preview)
emacs-buffer-list	List all buffers with metadata
emacs-read-file	Read a file from disk
emacs-write-file	Write content to a file
emacs-list-directory	List directory contents
emacs-find-in-files	Regex search across project files
emacs-shell-command	Execute shell commands
emacs-git-status	Git status (porcelain)
emacs-git-diff	Git diff (staged or working tree)
emacs-git-log	Recent commit log
emacs-editor-context	Current buffer, point, mode, region, project
emacs-org-execute	Execute org-babel source blocks
emacs-eval	Evaluate Emacs Lisp (opt-in, always prompts)

Metaprogramming (copilot-meta.el):

• Advice hooks — agent reacts to file save, compilation errors, git commits
• Introspection — describe-function, describe-variable, list-keybindings, list-packages, emacs-version-info
• Runtime tool generation — agent defines new tools mid-session via deftool
• Self-awareness — nursery-list, nursery-save, skills-list, skills-activate, skills-deactivate

Quick Actions

Copilot Quick (copilot-quick.el) — minibuffer-first AI interaction:

• M-x copilot-quick — ask a question, response streams in a side-window popup
• M-x copilot-quick-on-region — ask about selected text
• Keys in popup: q dismiss, y copy, i insert at point, c continue conversation
• No context switch — stays in your current buffer
• Configurable max height (copilot-quick-max-height, default 15)

Transient command menu — magit-style menu with every command organized:

M-x copilot-transient
├── Chat:      open · new session · resume · quick ask
├── Workflows: morning briefing · plan day · research · evening review
├── Code:      review · explain · tests · docs · refactor · debug
└── Settings:  tools browser · skills browser · model · effort · summaries

Command map (copilot-command-map) — prefix keymap, recommended binding C-c C-p:

Key	Command
c	Open chat
b	Morning briefing
r	Code review
e	Explain code
t	Generate tests
d	Generate docs
f	Refactor
q	Quick ask
SPC	Transient menu

Agent Trust — Diff Preview

Copilot Diff (copilot-diff.el) — preview agent edits before they land:

• When the agent edits a buffer, a diff preview appears in a side window
• Accept (C-c C-c / a), Reject (C-c C-k / r), Edit (e)
• Multi-hunk navigation (n / p)
• Auto-fallthrough in batch mode (tests still work)
• Toggle via copilot-diff-preview-enabled (default: on)

Life OS Tools

Tools that connect the agent to your personal knowledge infrastructure. All are feature-guarded — only registered when the backing package is loaded.

Tool	What It Does
org-agenda-today	Read today's org-agenda items
org-capture	Capture a task/note via org-capture
org-todo-toggle	Toggle TODO state of a heading
habits-due-today	List habits due today with status
habit-log	Mark a habit as DONE
elfeed-search	Search RSS entries by filter
elfeed-unread	Get unread RSS entries from last N days
elfeed-refresh	Refresh all RSS feeds
journal-today	Read today's journal entry
journal-search	Search journal entries by term
journal-write	Append to today's journal (with AI tagging)
org-roam-search	Search org-roam nodes by title/tag
org-roam-read	Read full content of an org-roam node
org-roam-create	Create org-roam node (with AI tagging)
org-roam-backlinks	Get backlinks to a node
contacts-search	Search org-contacts by name
contacts-create	Create a new contact
plan-read	Read the user's .plan file
plan-write	Update the .plan file
ai-authored-search	Find all AI-generated entries across org files

Workflows

Command	What It Does
M-x copilot-review	Review staged git changes
M-x copilot-explain	Explain region or buffer
M-x copilot-generate-tests	Generate test cases
M-x copilot-generate-docs	Generate documentation
M-x copilot-refactor	Analyze and refactor code
M-x copilot-debug	Debug with agent assistance
M-x copilot-morning-briefing	Structured morning synthesis (agenda, habits, feeds, journal)
M-x copilot-evening-review	Reflection and journaling workflow
M-x copilot-plan-day	Extended briefing → priority synthesis → journal + .plan update
M-x copilot-research	Multi-source search → synthesize → org-roam capture
M-x copilot-habit-log	Quick habit completion via completing-read
M-x copilot-journal-quick	Quick journal append from minibuffer

Ambient Intelligence

copilot-ambient-mode (copilot-ambient.el) — global minor mode (lighter: 🌊):

• Auto-briefing — morning briefing on first Emacs start of the day (10s delay)
• Idle prefetch — 60s idle → pre-gathers agenda, habits, feeds for instant workflow launch
• Periodic check-in — reads .plan every 2 hours, shows a reminder
• Evening nudge — after 5pm, suggests M-x copilot-evening-review
• State persisted across restarts (~/.copilot/ambient-state.el)
• Each feature individually toggleable via defcustom
• All features wrapped in condition-case — never crashes Emacs

Model Intelligence

• Header-line: current model, reasoning effort, summaries status
• Mode-line: [model/effort] alongside agent state
• M-x copilot-sdk-select-model — pick from available models
• M-x copilot-sdk-select-effort — set reasoning depth (low/medium/high/xhigh)
• M-x copilot-sdk-toggle-reasoning-summaries — toggle reasoning summaries
• Settings persist across Emacs restarts

Model Router

copilot-emacs-router.el — tier-based model routing:

• Three tiers — simple, moderate, complex — each mapped to a model
• Presets — switch routing strategy in one call:
  • copilot-emacs-router-preset-hybrid — fast model for simple, premium for complex
  • copilot-emacs-router-preset-fully-local — all tiers use a local model
• copilot-emacs-router-mode — minor mode that auto-routes based on prompt analysis
• Tiers, models, and presets are fully customizable via defcustom

Tool Nursery

copilot-emacs-nursery.el — three-tier tool lifecycle:

• Experimental → Promoted → Built-in — tools graduate based on usage
• copilot-emacs-nursery-save — persist a runtime-defined tool to disk
• copilot-emacs-nursery-promote — graduate a nursery tool to a permanent module
• copilot-emacs-nursery-list — browse nursery tools with usage stats
• Usage stats tracked automatically — call counts, last-used timestamps

Skills Framework

copilot-emacs-skills.el — prompt-injecting SKILL.md files:

• copilot-emacs-skills-discover — scan skills/ directory for available skills
• copilot-emacs-skills-activate — load a skill's SKILL.md into the system prompt
• copilot-emacs-skills-list-ui — interactive browser for all discovered skills
• 5 starter skills included in the skills/ directory:
  • elisp-expert — Emacs Lisp coding patterns and idioms
  • python-expert — Python development guidance
  • org-mode-expert — Org-mode workflows and best practices
  • org-roam-expert — Org-roam knowledge management
  • example — Template for creating new skills

Buffer Memory & Attention

copilot-buffer-mode (copilot-buffer.el) — three-tier buffer memory:

• L1 (Working) — buffers with unsaved changes, actively edited
• L2 (Recent) — recently visited buffers, decaying over time
• L3 (Reference) — everything else the agent can look up on demand
• Attention tracking — monitors buffer switches and edits to build context
• Scratch buffers — ephemeral workspaces for agent reasoning

Agent Coordination

Agent framework (copilot-agent.el) — multi-agent architecture:

• Agent registry — register, discover, and manage named agents
• Blackboard protocol — org-based shared state for inter-agent communication
• Indirect buffers — agents operate on indirect buffer clones for safe parallel edits

Org Write Tools

Full read-write org-mode integration — the agent can manage your task system:

• Create tasks — add TODO headings with deadlines and priorities
• Schedule & deadline — set/modify scheduled dates and deadlines
• Clock in/out — time tracking via org-clock
• Archive — archive completed items
• Refile — move headings between files and locations
• Tags & properties — set tags and arbitrary properties on headings

Autonomous Behaviors

Background workflows that run without prompting:

• Daily carry-forward — unfinished tasks auto-carried to today
• Weekly review — periodic synthesis of accomplishments and open items
• Session capture — automatic journaling of work sessions

PARA + GTD Integration

Structured knowledge management via org-roam:

• PARA areas — org-roam nodes organized as Projects, Areas, Resources, Archives
• Capture templates — quick-capture into the right PARA bucket
• Plan sync — per-project org-roam plans injected into every prompt via the SDK

@-Mentions & Context Injection

Type @ in the chat buffer and get CAPF-powered completion:

Mention	Injects
@file:path	File content
@buffer:name	Buffer content
@dir:path	Directory listing
@git-diff	Staged diff
@git-log	Recent commit log

AI Authorship Tagging

Journal entries and org-roam nodes created by the agent automatically get:

:PROPERTIES:
:AI_GENERATED: t
:AI_MODEL: claude-sonnet-4-20250514
:AI_TIMESTAMP: 2025-06-15T14:30:00-0500
:END:

The ai-authored-search tool finds all AI-generated entries across your org files — clean differentiation between human and AI content.

Requirements

• Emacs 28.1+
• GitHub Copilot CLI (copilot binary)
• copilot-sdk-elisp (ACP client library)
• transient (for copilot-transient menu, optional)

Installation

1. Clone both repos:

   git clone https://github.com/lqdev/copilot-sdk-elisp.git
   git clone https://github.com/lqdev/copilot-emacs.git

2. Add to your Emacs config:

   ;; SDK (protocol layer)
   (add-to-list 'load-path "/path/to/copilot-sdk-elisp")
   (require 'copilot-sdk)
   (require 'copilot-sdk-tools)
   
   ;; App (AI OS layer)
   (add-to-list 'load-path "/path/to/copilot-emacs")
   (require 'copilot-chat)
   (require 'copilot-emacs-tools)
   (require 'copilot-meta)
   (require 'copilot-workflows)
   (require 'copilot-quick)          ; minibuffer-first AI
   (require 'copilot-diff)           ; diff preview for agent edits
   (require 'copilot-ambient)        ; ambient intelligence (optional)
   (require 'copilot-emacs-nursery)  ; tool lifecycle (optional)
   (require 'copilot-emacs-skills)   ; skills framework (optional)
   (require 'copilot-emacs-router)   ; model routing (optional)
   
   ;; Configuration
   (setq copilot-sdk-cli-path "/path/to/copilot")
   (setq copilot-sdk-log-level "warning")
   
   ;; Enable ambient mode
   (copilot-ambient-mode 1)
   
   ;; Bind command map (recommended)
   (global-set-key (kbd "C-c C-p") copilot-command-map)

3. Open chat: M-x copilot-chat-open — or hit C-c C-p SPC for the transient menu.

Keybindings

Chat buffer

Key	Action
RET	Send message
C-c C-k	Cancel current operation
C-c C-n	New session
C-c C-q	Quit chat
C-c C-l	Clear buffer
C-c C-m	Select model
C-c C-p t	Tools browser
C-c C-p s	Skills browser
C-c C-p h	Resume session
C-c C-p b	Morning briefing

Quick popup

Key	Action
q	Dismiss popup
y	Copy response to kill ring
i	Insert response at point
c	Continue conversation

Diff preview

Key	Action
C-c C-c / a	Accept change
C-c C-k / r / q	Reject change
e	Edit target buffer at change location
n / p	Next / previous hunk

Architecture

┌─────────────────────────────────────────────────────┐
│  Ambient Layer (copilot-ambient.el)                  │
│  Auto-briefing · idle prefetch · check-ins · nudges  │
├─────────────────────────────────────────────────────┤
│  Interaction Layer                                    │
│  Chat UI + Quick Ask + Diff Preview + Transient Menu │
├─────────────────────────────────────────────────────┤
│  Intelligence Layer                                   │
│  82 tools + @-mentions + advice                       │
├─────────────────────────────────────────────────────┤
│  Extensibility Layer                                  │
│  Nursery (tool lifecycle) · Skills (SKILL.md prompt   │
│  injection) · Router (tier-based model routing)       │
├─────────────────────────────────────────────────────┤
│  copilot-sdk-elisp (ACP transport + tool framework)  │
├─────────────────────────────────────────────────────┤
│  Copilot CLI (copilot --acp --stdio)                 │
└─────────────────────────────────────────────────────┘

Files

File	Purpose
copilot-chat.el	Chat UI, transient menu, command map, @-mentions
copilot-emacs-tools.el	14 built-in Emacs tools
copilot-meta.el	Metaprogramming, introspection, Life OS tools, AI tagging
copilot-workflows.el	12 agentic workflows (code + Life OS)
copilot-quick.el	Minibuffer-first AI interaction
copilot-diff.el	Diff preview mode for agent edits
copilot-ambient.el	Ambient intelligence (background AI)
copilot-buffer.el	Buffer memory layer (L1/L2/L3 hierarchy, attention tracking, scratch buffers)
copilot-agent.el	Agent coordination (registry, blackboard protocol, indirect buffers)
copilot-emacs-nursery.el	Tool nursery — persist, promote, usage stats (three-tier lifecycle)
copilot-emacs-skills.el	Skills framework — discover, load, activate SKILL.md prompt injection
copilot-emacs-router.el	Model router — tier-based routing with presets (hybrid, fully-local)
skills/	5 starter skills (elisp-expert, python-expert, org-mode-expert, org-roam-expert, example)

Vision

Phase 1: Self-modification    ✅ Complete
Phase 2: Context injection    ✅ Complete
Phase 3: Cognitive workspace  ✅ Complete
Phase 4: Memory               ✅ Complete
Phase 5: Life OS              ✅ Complete
Phase 6: Unix citizen         ✅ Complete
Phase 7: Ambient intelligence ✅ Complete
Phase 8: Buffer memory & agents ✅ Complete
Phase 9: Integration & polish   ✅ Complete

Development

make compile   # Byte-compile
make test      # Run 94 ERT tests
make lint      # Checkdoc linting
make clean     # Remove .elc files

License

MIT