iris-dev 1.8.0

AI-powered CLI agent with controlled, structured access to your codebase

🤖 asgu

AI-powered CLI agent that gives language models controlled, structured access to your codebase through simple YAML instruction files.

Version: v1.6 — April 9, 2026

---

😤 The Problem with Existing AI Coding Agents

Most AI coding tools today share the same fundamental flaws:

• 🚫 No boundaries. The agent reads and modifies whatever it wants across your entire project. One wrong instruction and critical files get overwritten or deleted.
• 🎲 No structure. You write a prompt in natural language, the AI guesses what files to touch, and you hope for the best.
• 👻 No accountability. After the agent runs, you have no clear record of what changed, why, or what it noticed along the way.
• 💸 Token waste. Feeding the entire codebase into context on every request is slow and expensive.
• 🐛 Logical errors go unnoticed. If there's no console error, most agents won't catch that styles aren't applied or that an import is pointing at the wrong file.

Tools like Cursor, Copilot, and other agents are powerful — but they operate with too much freedom and too little transparency for serious development workflows.

---

✅ What asgu Does Differently

asgu introduces a YAML instruction file that you write before the agent runs. This file defines exactly what the agent can read, what it can write, what it must never touch, and what it needs to fix. The agent operates strictly within these boundaries.

You stay in control. The agent stays in its lane.

---

⚙️ How It Works

1. 📝 You create a .yaml instruction file in your project folder
2. ▶️ You run asgu run <file.yaml> in the terminal
3. 🤖 asgu reads your instruction, collects the relevant context, sends a structured prompt to the AI model, parses the response, and writes only the files you allowed
4. 📊 Optionally, it saves a report with what changed, tips from the model, and a backup of the original files

---

🛠️ Stack

• Language: Python
• AI model: qwen2.5-coder:7b via Ollama (runs fully locally, no API key needed)
• Libraries:
  • ollama — local model inference
  • pyyaml — YAML instruction parsing
  • pyinstaller — builds the project into a standalone .exe

---

📦 Installation

Requirements: Python 3.10+, Ollama installed and running

# Install dependencies
pip install ollama pyyaml

# Pull the model
ollama pull qwen2.5-coder:7b

# Clone the repo and build
git clone https://github.com/yourname/asgu
cd asgu
pyinstaller --onefile --hidden-import=ollama asgu.py

The asgu.exe will appear in the dist/ folder.

---

🚀 Commands

asgu init

asgu init

asgu — setup

Enter project path: C:/Users/user/projects/my-app
Project saved. Now run: asgu run <file.yaml>

The project path is saved to asgu.config.json next to the executable.

---

asgu run <file.yaml>

asgu run landing.yaml

asgu — running landing.yaml

[1/4] Collecting context...
[2/4] Sending request to Ollama...
[3/4] Applying changes...
  [WRITTEN]  src/App.jsx
  [WRITTEN]  src/App.css
[4/4] Finalizing...
  [REPORT]   asgu_report.yaml

  [TIPS]
  > App.css should also be imported in src/main.jsx

asgu — done (2 file(s) changed)

---

asgu undo

Rolls back changes to all files that were modified in the last run, using the backup saved in asgu_report.yaml.

asgu undo

asgu — undo

  [RESTORED]  src/App.jsx
  [RESTORED]  src/App.css

asgu — done (2 file(s) restored)

Requires backup: true in the instruction file used for the previous run.

---

asgu status

Shows the current project path and the last instruction that was run.

asgu status

asgu — status

  Project:   C:/Users/user/projects/my-app
  Last run:  landing.yaml
  Changed:   src/App.jsx, src/App.css
  Backed up: yes

---

📋 YAML Instruction Syntax

Full example

task: "Create a landing page for a clothing store"

model: qwen2.5-coder:7b

access:
  read: true
  write:
    - src/App.jsx
    - src/App.css
  forbidden:
    - .env
    - src/main.jsx

reference:
  - references/example.css
  - references/layout.html

error: |
  TypeError: Cannot read properties of undefined at App.jsx:15
  Styles from App.css are not applied to the page.

instructions:
  - Create a hero section with a title, subtitle and a button
  - Create a products section with 3 product cards
  - Add a footer with contact info
  - Import App.css at the top of App.jsx

feedback: true
tips: true
backup: true

---

🔧 Parameters

Parameter	Type	Required	Description
task	string	✅ yes	Short description of what the agent should do
model	string	➖ no	Ollama model to use (default: qwen2.5-coder:7b)
access.read	true / false / list	✅ yes	Controls what the agent can read for context
access.write	list	✅ yes	Files the agent is allowed to modify or create
access.forbidden	list	➖ no	Files the agent must never touch
reference	list	➖ no	Paths to example files (HTML, CSS) used as style reference
error	string	➖ no	Console error or description of a logical bug to fix
instructions	list	✅ yes	Step-by-step instructions for the agent
feedback	boolean	➖ no	Save a report to asgu_report.yaml after the run
tips	boolean	➖ no	Ask the model to report issues outside the write zone
backup	boolean	➖ no	Save original file contents to the report before overwriting

---

👁️ access.read modes

# Read the entire project (excludes forbidden and .yaml files)
read: true

# Read nothing — agent only sees the write files
read: false

# Read specific files only
read:
  - src/App.jsx
  - src/main.jsx

---

🐛 error — console or logical errors

Paste any error directly:

error: |
  Module not found: Error: Can't resolve './App.css'
  at ./src/App.jsx

Or describe a logical issue:

error: |
  The button click does not trigger any action.
  The counter does not increment when clicked.

---

🎨 reference — example files

Point the agent to existing HTML or CSS files to use as a style reference:

reference:
  - references/old_design.css
  - references/example_layout.html

---

💾 backup + asgu undo — rollback support

When backup: true, the original contents of all write files are saved to asgu_report.yaml before any changes are made. If the result is wrong, run asgu undo to restore everything automatically.

---

📊 Report format

When feedback: true, asgu writes asgu_report.yaml to your project folder:

task_completed: Create a landing page for a clothing store
changed_files:
  - src/App.jsx
  - src/App.css
tips:
  - App.css import is missing in src/main.jsx
backup:
  src/App.jsx: |
    // original file content before changes

---

🚫 What the Agent Cannot Do

• ❌ Delete files
• ❌ Run shell commands (npm install, git, etc.)
• ❌ Access files outside the project path
• ❌ Write files not listed in access.write
• ❌ Read files listed in access.forbidden

---

🗺️ Roadmap

✅ v1.6 — current

• asgu init, run, undo, status
• model parameter — choose the model inside the YAML
• error parameter — pass a bug or console error directly
• reference parameter — example files for context
• instructions as a list instead of a plain string
• asgu undo — one-command rollback from backup

🔜 v1.7 — planned

• asgu run a.yaml b.yaml — run multiple instructions at once
• asgu history — view past runs
• asgu validate <file.yaml> — check YAML syntax before running
• functions: sub-parameter for read, write, forbidden — function-level access control inside a file

---

📄 License

asgu Source Available License Copyright (c) 2026 Anasteyshen666

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated source code (the "Software"), to use, run, and study the Software for personal or commercial purposes, subject to the following conditions:

1. ATTRIBUTION REQUIRED Any modified version of the Software that is publicly distributed must clearly state that it is based on asgu by Anasteyshen and include a link to the original repository. This notice must appear in the documentation, README, or any other prominent place in the modified work.

2. NO SALE OF MODIFICATIONS WITHOUT PERMISSION You may not sell, sublicense, or otherwise commercially distribute any modified version of the Software without prior written permission from the author (Anasteyshen). Selling or monetizing the Software in its original, unmodified form is also not permitted without permission.

3. WHAT YOU CAN DO (without asking)

   • Use the Software for any personal or commercial project
   • Read and study the source code
   • Share the original, unmodified Software with proper credit
   • Fork and modify the Software for private use

4. WHAT REQUIRES PERMISSION

   • Publishing or distributing a modified version
   • Selling or monetizing any version of the Software
   • Using the name "asgu" or the author's name to promote a derived product

To request permission, contact: [e-mail]

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

MIT