Commit 9b90cee
Changed files (1)
README.md
@@ -1,74 +1,61 @@
# Elelem
-Fast, correct, autonomous - Pick two
+Fast, correct, autonomous – pick two.
-PURPOSE:
+## Purpose
-Elelem is a minimal coding agent written in Ruby. It is intended to
-assist me (a software engineer and computer science student) with writing,
-editing, and managing code and text files from the command line. It acts
-as a direct interface to an LLM, providing it with a simple text-based
-UI and access to the local filesystem.
+Elelem is a minimal coding agent written in Ruby. It is designed to help
+you write, edit, and manage code and plain-text files from the command line
+by delegating work to an LLM. The agent exposes a simple text-based UI and a
+set of built-in tools that give the LLM access to the local file system
+and Git.
-DESIGN PRINCIPLES:
+## Design Principles
-- Follows the Unix philosophy: simple, composable, minimal.
-- Convention over configuration.
-- Avoids unnecessary defensive checks, or complexity.
-- Assumes a mature and responsible LLM that behaves like a capable engineer.
-- Designed for my workflow and preferences.
-- Efficient and minimal like aider - https://aider.chat/
-- UX like Claude Code - https://docs.claude.com/en/docs/claude-code/overview
+* Unix philosophy – simple, composable, minimal.
+* Convention over configuration.
+* No defensive checks or complexity beyond what is necessary.
+* Assumes a mature, responsible LLM that behaves like a capable engineer.
+* Optimised for my personal workflow and preferences.
+* Efficient and minimal like *aider* – https://aider.chat/.
+* UX similar to Claude Code – https://docs.claude.com/en/docs/claude-code/overview.
-SYSTEM ASSUMPTIONS:
+## System Assumptions
-- This script is used on a Linux system with the following tools: Alacritty, tmux, Bash, and Vim.
-- It is always run inside a Git repository.
-- All project work is assumed to be version-controlled with Git.
-- Git is expected to be available and working; no checks are necessary.
+* Linux host with Alacritty, tmux, Bash, Vim.
+* Runs inside a Git repository.
+* Git is available and functional.
-SCOPE:
+## Scope
-- This program operates only on code and plain-text files.
-- It does not need to support binary files.
-- The LLM has full access to execute system commands.
-- There are no sandboxing, permission, or validation layers.
-- Execution is not restricted or monitored - responsibility is delegated to the LLM.
+Only plain-text and source-code files are supported. No binary handling,
+sandboxing, or permission checks are performed - the LLM has full access.
-CONFIGURATION:
+## Configuration
-- Avoid adding configuration options unless absolutely necessary.
-- Prefer hard-coded values that can be changed later if needed.
-- Only introduce environment variables after repeated usage proves them worthwhile.
+Prefer convention over configuration. Add environment variables only after
+repeated use proves their usefulness.
-UI EXPECTATIONS:
+## UI Expectations
-- The TUI must remain simple, fast, and predictable.
-- No mouse support or complex UI components are required.
-- Interaction is strictly keyboard-driven.
+Keyboard-driven, minimal TUI. No mouse support or complex widgets.
-CODING STANDARDS FOR LLM:
+## Coding Standards for the LLM
-- Do not add error handling or logging unless it is essential for functionality.
-- Keep methods short and single-purpose.
-- Use descriptive, conventional names.
-- Stick to Ruby's standard library whenever possible.
+* No extra error handling unless essential.
+* Keep methods short, single-purpose.
+* Descriptive, conventional names.
+* Use Ruby standard library where possible.
-HELPFUL LINKS:
+## Helpful Links
-- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
-- https://www.anthropic.com/engineering/writing-tools-for-agents
-- https://simonwillison.net/2025/Sep/30/designing-agentic-loops/
+* https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+* https://www.anthropic.com/engineering/writing-tools-for-agents
+* https://simonwillison.net/2025/Sep/30/designing-agentic-loops/
## Installation
-Install the gem and add to the application's Gemfile by executing:
-
-```bash
-bundle add elelem
-```
-
-If bundler is not being used to manage dependencies, install the gem by executing:
+Install the gem directly:
```bash
gem install elelem
@@ -84,47 +71,85 @@ elelem chat
### Options
-- `--host`: Specify Ollama host (default: localhost:11434)
-- `--model`: Specify Ollama model (default: gpt-oss, currently only tested with gpt-oss)
-- `--token`: Provide authentication token
+* `--host` – Ollama host (default: `localhost:11434`).
+* `--model` – Ollama model (default: `gpt-oss`).
+* `--token` – Authentication token.
### Examples
```bash
-# Chat with default model
+# Default model
elelem chat
-# Chat with specific model and host
+# Specific model and host
elelem chat --model llama2 --host remote-host:11434
```
-### Features
+## Mode System
-- **Interactive REPL**: Clean command-line interface for chatting
-- **Mode System**: Control agent capabilities with workflow modes (plan, build, verify, auto)
-- **Tool Execution**: Execute shell commands, read/write files, search code
-- **Streaming Responses**: Real-time streaming of AI responses
-- **Conversation History**: Maintains context across the session
+The agent exposes six built‑in tools. You can switch which ones are
+available by changing the *mode*:
-### Mode System
+| Mode | Enabled Tools |
+|---------|------------------------------------------|
+| plan | `grep`, `list`, `read` |
+| build | `grep`, `list`, `read`, `patch`, `write` |
+| verify | `grep`, `list`, `read`, `execute` |
+| auto | All tools |
-Control what tools the agent can access:
+Use the following commands inside the REPL:
-```bash
-/mode plan # Read-only (grep, list, read)
-/mode build # Read + Write (grep, list, read, patch, write)
-/mode verify # Read + Execute (grep, list, read, execute)
-/mode auto # All tools enabled
+```text
+/mode plan # Read‑only
+/mode build # Read + Write
+/mode verify # Read + Execute
+/mode auto # All tools
+/mode # Show current mode
```
-Each mode adapts the system prompt to guide appropriate behavior.
+The system prompt is adjusted per mode so the LLM knows which actions
+are permissible.
+
+## Features
+
+* **Interactive REPL** – clean, streaming chat.
+* **Toolbox** – file I/O, Git, shell execution.
+* **Streaming Responses** – output appears in real time.
+* **Conversation History** – persists across turns; can be cleared.
+* **Context Dump** – `/context` shows the current conversation state.
+
+## Toolbox Overview
+
+The `Toolbox` class is defined in `lib/elelem/toolbox.rb`. It supplies
+six tools, each represented by a JSON schema that the LLM can call.
+
+| Tool | Purpose | Parameters |
+| ---- | ------- | ---------- |
+| `grep` | Search Git‑tracked files | `query` |
+| `list` | List tracked files | `path` (optional) |
+| `read` | Read file contents | `path` |
+| `write` | Overwrite a file | `path`, `content` |
+| `patch` | Apply a unified diff via `git apply` | `diff` |
+| `execute` | Run shell commands | `cmd`, `args`, `env`, `cwd`, `stdin` |
+
+## Tool Definition
+
+The core `Tool` wrapper is defined in `lib/elelem/tool.rb`. Each tool is
+created with a name, description, JSON schema for arguments, and a block
+that performs the operation. The LLM calls a tool by name and passes the
+arguments as a hash.
+
+## Known Limitations
-## Development
+* Assumes the current directory is a Git repository.
+* No sandboxing – the LLM can run arbitrary commands.
+* Error handling is minimal; exceptions are returned as an `error` field.
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Contributing
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Feel free to open issues or pull requests. The repository follows the
+GitHub Flow.
## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT – see the bundled `LICENSE.txt`.