xbcsmith/xzatoma

Profil xbcsmith

Dernière activité source enregistrée: 4 avril 2026 à 13:14

Catalogue SkillsMP mis à jour: 17 octobre 2026 à 00:09

skills collectés: 3

Étoiles GitHub: 0
Forks GitHub: 0

README du dépôt

Fichier source du README : README.md

Lire le README source

Afficher le README complet

# XZatoma Experimental Autonomous AI Agent [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://www.rust-lang.org) [![Status](https://img.shields.io/badge/status-planning-yellow.svg)](docs/explanation/implementation_plan.md) **Use at your own risk. This is a learning project.** ## Overview XZatoma is a simple autonomous AI agent CLI written in Rust that executes tasks through conversation with AI providers (GitHub Copilot or Ollama). Think of it as a command-line version of Zed's agent chat - you give it a goal (via interactive prompt or structured plan), and it uses basic file and terminal tools to accomplish it. ### Key Features - **Multi-Provider AI Integration**: GitHub Copilot and Ollama support - **Autonomous Agent**: Conversation-based execution with multi-turn tool calling - **Context Mentions**: Include files, search results, and web content with `@mention` syntax - **Basic Tools**: File operations (list, read, write, delete, diff) and terminal execution - **Flexible Input**: Interactive chat mode, structured plan files, or one-shot prompts - **Conversation History**: Persist chat sessions locally; use `xzatoma history list` to view sessions, `xzatoma chat --resume <ID>` to resume, and `xzatoma history delete --id <ID>` to delete a session (see `docs/how-to/manage_conversation_history.md`). You can override the history database path with `xzatoma chat --storage-path <PATH>` (or any other subcommand) or by setting the environment variable `XZATOMA_HISTORY_DB` to point to an alternate `history.db` file. - **Zed IDE Integration**: Run as an ACP stdio subprocess for [Zed](https://zed.dev) agent panel integration - **Generic Design**: No specialized features - agent uses basic tools creatively ## Quick Start ### Installation (Coming Soon) ```bash # From source cargo install --git https://github.com/xbcsmith/xzatoma # Or download binary # See releases page ``` ### Usage Example ```bash # Authenticate with provider xzatoma auth --provider copilot # Interactive chat mode (default: Planning mode) xzatoma chat # Interactive chat in Write mode with safety enabled xzatoma chat --mode write --safe # Run a plan file xzatoma run --plan task.yaml # One-shot prompt xzatoma run --prompt "Find all TODO comments and create tasks.md" # Run as an ACP stdio agent subprocess for Zed IDE # (configure xzatoma as an agent server in Zed settings) xzatoma agent # Use a specific provider in agent mode xzatoma agent --provider ollama --model granite4:3b ``` ### Example Plan File ```yaml goal: "Find all TODO comments and create a summary file" context: directory: "src/" instructions: - List all Rust files in src/ - Read each file and find TODO comments - Create tasks.md with all TODO items - Include file name and line number for each ``` ### Example Interactive Session #### Planning Mode (Read-Only Analysis) ```bash $ xzatoma chat ╔══════════════════════════════════════════════════════════════╗ ║ XZatoma Interactive Chat Mode - Welcome! ║ ╚══════════════════════════════════════════════════════════════╝ Mode: PLANNING (Read-only mode for creating plans) Safety: SAFE (Confirm dangerous operations) Type '/help' for available commands, 'exit' to quit [PLANNING][SAFE][Copilot: gpt-5.3-codex] >>> Analyze the project structure and create a refactoring plan Agent: I'll analyze your project structure. [Using tool: list_files] [Using tool: read_file for key files] Here's the project structure: - src/main.rs: CLI entry point - src/agent/: Core agent logic - src/tools/: Available tools I recommend the following refactoring... [PLANNING][SAFE][Copilot: gpt-5.3-codex] >>> /write Switched from PLANNING to WRITE mode [WRITE][SAFE][Copilot: gpt-5.3-codex] >>> Now implement the refactoring plan ``` #### Write Mode (File Modifications) ```bash $ xzatoma chat --mode write --safe [WRITE][SAFE][Copilot: gpt-5.3-codex] >>> Refactor all snake_case function names to camelCase Agent: I'll refactor the function names for you. [Using tool: read_file] [Using tool: write_file] Please confirm: Overwriting src/lib.rs with 245 lines yes [Using tool: terminal] Running cargo fmt... Done! Refactored 12 functions across 5 files. ``` ## Zed Integration XZatoma can run as a custom External Agent for the [Zed](https://zed.dev) editor using the Agent Client Protocol (ACP). Add it as a custom agent in your Zed settings to access it in the Agent Panel and Threads Sidebar. Open the Command Palette, run `agent: open settings`, go to **External Agents**, click **Add Agent**, and choose **Add Custom Agent**. Replace the placeholder with: ```json { "agent_servers": { "xzatoma": { "type": "custom", "command": "xzatoma", "args": ["agent"], "env": {} } } } ``` The `xzatoma agent` command: - communicates over stdin/stdout using the Agent Client Protocol (ACP) - supports text and vision prompts (vision requires a multimodal model) - runs as a stateful subprocess with per-workspace conversation history - forces all tracing and diagnostic output to stderr so stdout stays clean Use `dev: open acp logs` from the Command Palette to inspect ACP messages when debugging. See `docs/how-to/zed_acp_agent_setup.md` for full setup instructions including provider-specific configuration, MCP forwarding, and troubleshooting. ## How It Works XZatoma is intentionally simple: 1. **You provide a goal** - via interactive chat or plan file 2. **Agent talks to AI provider** - sends conversation with available tools 3. **AI decides what to do** - calls tools (list files, read file, write file, run command) 4. **Agent executes tools** - runs the requested operations 5. **Repeat until done** - agent adds results to conversation, AI continues The agent has no specialized features - it accomplishes complex tasks by using basic file and terminal tools creatively. ### Chat Modes for Fine-Grained Control XZatoma provides two complementary chat modes to control what the agent can do: **Planning Mode** (Read-Only) - Explore and analyze code - Create and review plans - Safe - agent cannot modify files or run commands - Start here to understand what needs to be done **Write Mode** (Read/Write) - Implement changes - Execute commands and scripts - Modify and create files - Use after reviewing a plan in Planning mode Both modes support **Safety Mode** for additional protection: - **Safe** - Agent must confirm before dangerous operations - **YOLO** - Execute without confirmations (faster, riskier) Switch between modes at any time during your chat session - conversation history is preserved! Note: The interactive prompt now shows provider and model when available (for example: `[PLANNING][SAFE][Copilot: gpt-5.3-codex] >>>`). Provider labels are shown in white and model names in green on terminals that support ANSI colors. For detailed usage guide, see [Using Chat Modes](docs/how-to/use_chat_modes.md). ## Context Mentions XZatoma supports context mentions - a powerful way to inject relevant content directly into your prompts: ```text Include a file: @config.yaml Specific lines: @src/main.rs#L10-25 Search your code: @search:"error handling" Regex patterns: @grep:"^pub fn.*Result" Web content: @url:https://docs.example.com ``` Instead of having the agent discover content through tool calls, mentions pre-load context, making interactions faster and more efficient. The agent sees full context without needing to explore. For complete guide, see [Using Context Mentions](docs/how-to/use_context_mentions.md). ## File Editing Safety XZatoma includes intelligent file editing with multiple safety mechanisms to prevent accidental data loss: ### Editing Modes - **create**: Create new files (fails if file exists) - **edit**: Targeted replacement using unique anchor text (SAFEST for modifications) - **append**: Add content to end of file (SAFEST for additions) - **overwrite**: Replace entire file (USE WITH CAUTION) ### Safety Features 1. **Required anchor text**: Edit mode requires `old_text` parameter 2. **Uniqueness validation**: Anchor text must match exactly once 3. **Change magnitude detection**: Blocks edits that dramatically reduce file size 4. **Diff preview**: All changes shown before being applied 5. **Clear error messages**: Guidance on correct usage when errors occur ### Example: Safely Adding to a Makefile Instead of risking file replacement, use append mode: ```bash xzatoma --write "Add a release-linux target to the Makefile that runs cargo build --release for x86_64-unknown-linux-gnu" ``` The agent will use append mode to safely add content: ```json { "path": "Makefile", "mode": "append", "content": "\nrelease-linux:\n\t@cargo build --release --target x86_64-unknown-linux-gnu\n" } ``` This safely adds to the file without touching existing content. ## Project Documentation ### For Users - [How to Use Chat Modes](docs/how-to/use_chat_modes.md) - Interactive chat mode guide - [Using Context Mentions](docs/how-to/use_context_mentions.md) - Include files, searches, and URLs in prompts - [How to Manage Conversation History](docs/how-to/manage_conversation_history.md) - List, resume, and delete saved sessions - [Quick Start Tutorial](docs/tutorials/quickstart.md) _(coming soon)_ - [Configuration Guide](docs/how-to/configure_providers.md) _(coming soon)_ - [CLI Reference](docs/reference/cli.md) _(coming soon)_ ### For Developers - [Chat Modes Architecture](docs/explanation/chat_modes_architecture.md) - Design and implementation - [Context Mention Architecture](docs/explanation/context_mention_architecture.md) - Multi-source context injection - [Context Mention Implementation](docs/explanation/context_mention_implementation_summary.md) - Complete implementation details - [Architecture Overview](docs/reference/architecture.md) - [Implementation Plan](docs/explanation/implementation_plan.md) - [Project Overview](docs/explanation/overview.md) - [Quick Reference](docs/reference/quick_reference.md) ### Project Guidelines - [Planning Guidelines](PLAN.md) - [Agent Development Guidelines](AGENTS.md) ## Project Status **Current Phase**: Planning Complete **Next Milestone**: Phase 1 - Foundation **Target Release**: v1.0.0 (14-19 weeks) See [Implementation Plan](docs/explanation/implementation_plan.md) for details. ## Implementation Phases 1. **Phase 1: Foundation** (2-3 weeks) - Core infrastructure, config, error handling 2. **Phase 2: AI Providers** (2-3 weeks) - GitHub Copilot and Ollama integration 3. **Phase 3: Agent Core** (2-3 weeks) - Agent execution loop and basic tools 4. **Phase 4: Plans & CLI** (2-3 weeks) - Plan parsing and CLI commands 5. **Phase 5: Production** (2 weeks) - Polish, documentation, and release ## Architecture XZatoma follows a modular architecture with clear separation of concerns: ```text User Input → CLI → Agent Core → AI Provider ↓ ↓ Tools ← ─ ─ ─ ─ ─ ┘ (File ops, Terminal) ``` See [Architecture Document](docs/reference/architecture.md) for complete details. ## Contributing We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) _(coming soon)_ and follow the guidelines in [AGENTS.md](AGENTS.md). ### Development Setup ```bash # Clone repository git clone https://github.com/xbcsmith/xzatoma.git cd xzatoma # Build project cargo build # Run tests cargo test # Check code quality cargo fmt --check cargo clippy -- -D warnings ``` ## Technology Stack - **Language**: Rust (stable) - **Async Runtime**: Tokio - **CLI Framework**: Clap - **AI Providers**: GitHub Copilot, Ollama - **Tools**: File ops, terminal execution - **Testing**: >80% coverage target ## License Apache License 2.0 - See [LICENSE](LICENSE) for details. ## Acknowledgments This project draws inspiration from: - [Zed](https://github.com/zed-industries/zed) - Agent chat and tool integration patterns - [Goose](https://github.com/block/goose) - Agent architecture and provider abstraction - [Diataxis](https://diataxis.fr/) - Documentation organization ## Contact - **Issues**: [GitHub Issues](https://github.com/xbcsmith/xzatoma/issues) - **Discussions**: [GitHub Discussions](https://github.com/xbcsmith/xzatoma/discussions) --- **Status**: Planning Complete | **Version**: 0.1.0-planning | **Last Updated**: 2025-01-07

Chargement du README du dépôt…

Skills dans ce dépôt

Analystes, journalistes et reporters Développeurs de logiciels Ouvreuses, préposés au hall et préposés aux billets Porteurs de bagages et grooms

5 catégories métier · 100% classifié

skill

métier

description

mis à jour

greet

Ouvreuses, préposés au hall et préposés aux billetsPorteurs de bagages et grooms

Greet the user with a friendly personalized message

Langue du texte source : anglais

2026-04-04

summarize

Rédacteurs en chefAnalystes, journalistes et reporters

Condense provided text into a concise summary

Langue du texte source : anglais

2026-04-04

write-file

Développeurs de logiciels

Write provided content to a named file in the output directory

Langue du texte source : anglais

2026-04-04

Affichage de 3 skills collectés sur 3.

Installer avec un assistant IA

Copiez ce prompt dans l’assistant IA que vous utilisez.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/xbcsmith/xzatoma.