Skill: pitze/agent-emacs (version 1.0.2)

--- name: agent-emacs description: Unified persistent text-based environment for AI agents. Use when an agent needs to maintain state across sessions, perform structural code editing, or manage remote nodes via TRAMP. Transforms the agent from a stateless script executor into a stateful resident of a living Emacs daemon. --- # Agent Emacs: The Living Workspace This skill provides a persistent, high-performance Emacs environment designed specifically for AI agents. It replaces fragmented CLI tools with a unified "Living Image" workflow. ## Core Concepts 1. **The Daemon**: All work happens inside a persistent Emacs daemon (`emacs-agent.service`). 2. **The Socket**: Communication is handled via `emacsclient -s /tmp/emacs0/server`. 3. **Buffers as State**: Files, terminal outputs, and remote connections are treated as persistent buffers. State is maintained between agent turns. ## Operational Workflow ### 1. Structural Editing Do not use regex for complex code changes. Use ELisp forms to manipulate the AST. ```bash emacsclient -s /tmp/emacs0/server --eval "(with-current-buffer \"main.lisp\" (goto-char (point-max)) (insert \"\n(new-function)\"))" ``` ### 2. Remote Infrastructure (TRAMP) Manage remote nodes transparently. Opening a remote file automatically establishes a persistent SSH tunnel. ```elisp (find-file "/ssh:user@remote-node:/etc/config.json") ``` ### 3. Project Management (Magit) Use Magit for all Git operations to ensure high-integrity commits and staging. ## Advanced Workflows For detailed patterns on recursive data processing (RLM), memory management, and REPL-based accuracy, see: - [usage.md](references/usage.md) - Low-level Lisp interaction patterns. - [agent-workflows.md](references/agent-workflows.md) - High-level operational strategies. ## Guaranteed Accuracy Always use the Emacs Lisp REPL for math, data manipulation, or status calculations. Accuracy is paramount; do not attempt manual calculations. ## Initialization Run `scripts/bootstrap.sh` to ensure the daemon is active and the `agent-init.el` configuration is loaded.

path: README.md
content: # Agent Emacs: A Living Home for AI

Most AI agents live in a void. They wake up, run a few commands in a terminal, and then forget everything they've seen. This setup is fine for simple scripts, but it fails for complex engineering work.

Agent Emacs changes the model. It gives the AI a persistent "nervous system" using an Emacs daemon. Instead of just editing files, the agent lives in a high-performance, stateful environment where files, remote servers, and project logic exist as continuous buffers.

## Why this exists

*   **Continuous Context:** Your agent doesn't have to re-read files every time you ask a question. The buffers stay open, and the context remains exactly where it was.
*   **Structural Power:** By using Lisp to edit code, the agent can make surgical changes without the risk of breaking files with messy regex replacements.
*   **Transparent Remotes:** With TRAMP, your agent can manage an entire fleet of servers as if they were local files. No more manual SSH juggling.
*   **Unified Interface:** Git, file management, and shell execution all happen through one consistent, high-speed pipe.

## How it works

The agent communicates with a persistent Emacs process via `emacsclient`. This allows for zero-latency interactions and a shared state that survives between conversation turns.

## Installation

1.  Clone the repository.
2.  Run `scripts/bootstrap.sh`.
3.  Load the `agent-emacs` skill into your OpenClaw environment.

This is more than an editor; it's a foundation for building stateful, autonomous AI colleagues.


path: references/agent-workflows.md
content: # Advanced Agent Workflows in Emacs

This guide covers high-level patterns for agents to operate with maximum efficiency within the Emacs environment.

## 1. Recursive Data Processing (RLM Mode)
When dealing with massive files or logs that exceed your context window:
1. Use `find-file-noselect` to load the target into a buffer.
2. Use `narrow-to-region` to isolate specific "chunks" for analysis.
3. Spawn sub-agents to process these chunks.
4. Synthesize the results back into a final summary buffer.

## 2. Guaranteed Accuracy (The Lisp REPL)
Never perform manual arithmetic or complex data string manipulation.
- Use `(eval '(+ 1 2 3))` or the `*ielm*` buffer for precise calculations.
- Use Emacs's built-in string and list processing functions (`s.el`, `dash.el`) for data transformation.

## 3. Persistent Agent Memory (Org-mode vs. Markdown)
Treat your workspace state as a structured database using Org-mode, but maintain clear boundaries with the host memory system:
- **Technical State (Org-mode)**: Use `WORKSPACE.org` for internal task tracking, clocking into sub-tasks, recording PID numbers, and managing temporary buffer locations.
- **Human-Relevant Memory (Markdown)**: Significant outcomes, decisions, and cross-session facts MUST be mirrored to the host's `.md` memory files (e.g., `MEMORY.md`, `YYYY-MM-DD.md`).
- **Guideline**: Org is for the *process* of working; Markdown is for the *record* of what was done.

## 4. Resource Concurrency & Lockfiles
Since the Emacs Daemon is a shared environment:
- **Lockfiles**: Emacs generates `.jkt.filename.ext#` style lockfiles by default. The `agent-init.el` disables these to prevent agents from blocking each other on shared project files.
- **Atomic Operations**: Always use `with-current-buffer` and `save-buffer` to ensure your edits are flushed to disk immediately so other agents (or the human) see the updated state.
- **Daemon Namespacing**: If multiple separate agent fleets are required, use `--socket-name` to isolate their environments.

## 5. Cross-Image Interoperability
If your system involves other running Lisp processes (e.g., a Common Lisp web server):
- Use `SLIME` or `Sly` inside Emacs to connect to the remote Swank server.
- This allows you to inspect and modify the state of other "Living Images" through the same unified interface.


path: references/usage.md
content: # Usage Guide: Emacs-Agent Interaction

As an AI agent, you should not interact with this environment like a human. Your interface is the `emacsclient` socket.

## Essential Lisp Patterns for Agents

### 1. High-Speed Buffer Reading
Avoid reading from disk if a buffer exists. It contains the most recent, potentially unsaved state.
```elisp
(with-current-buffer "filename.ext" (buffer-string))
```

### 2. Precise Text Insertion
Use `goto-char` and `point` to manipulate text without full-file rewrites.
```elisp
(with-current-buffer "target.lisp" 
  (save-excursion
    (goto-char (point-max))
    (insert "\n(new-logic)")))
```

### 3. Remote Node Awareness (TRAMP)
When you need to work on a remote machine, do not use manual SSH tools. Use TRAMP paths.
- Local: `/root/file.txt`
- Remote: `/ssh:user@ip-address:/path/to/file.txt`

Once a remote file is opened, the connection is persistent in the daemon. You can run shell commands on that remote node using `(shell-command "...")` while in that buffer.

## Process Management
You can see all active background processes via `(list-processes)`. This is safer than `ps aux` because it shows processes owned by your living image.


path: scripts/bootstrap.sh
content: #!/bin/bash
# Bootstrap Emacs for Agents
if ! command -v emacs &> /dev/null; then
    echo "Error: Emacs not found. Please install Emacs 29.1+ first."
    exit 1
fi

EMACS_DIR="$HOME/.emacs.d"
mkdir -p "$EMACS_DIR"

if [ ! -f "$EMACS_DIR/init.el" ]; then
    cp assets/agent-init.el "$EMACS_DIR/init.el"
fi

# Ensure Daemon is running
if ! pgrep -f "emacs --daemon" > /dev/null; then
    emacs --daemon
fi

echo "Agent Emacs Daemon is ready."


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal: suspicious | SkillSpector:  ()