iris-dev 1.8.4

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

Iris

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

Version: v1.8.3 — May 15, 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 Iris Does Differently

Iris 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 iris run <file.yaml> in the terminal
3. Iris 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
  • windows-curses — TUI interface

---

Installation

pip install iris-dev

Or build from source:

# Requirements: Python 3.10+, Ollama installed and running
git clone https://github.com/Anasteyshen/iris
cd iris
pip install ollama pyyaml windows-curses

---

Commands

iris init

iris init

iris — setup

Select a profile:
  [1] unity — Unity game projects
  [2] web — Web projects (HTML/CSS/JS)
  [3] python — Python libraries and scripts
  [4] cli — CLI tools
  [5] custom — Manual configuration

Profile (1-5): 2
Enter project path: C:/Users/user/projects/my-app
Project saved: C:/Users/user/projects/my-app
Profile:       web

---

iris run <file.yaml> [file2.yaml ...]

iris run landing.yaml

iris — 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]   iris_report.yaml

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

iris — done (2 file(s) changed)

You can also run multiple instruction files in sequence:

iris run layout.yaml styles.yaml logic.yaml

---

iris undo

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

iris undo

iris — undo

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

iris — undo complete

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

---

iris validate <file.yaml>

Checks a YAML instruction file for errors before running it.

iris validate landing.yaml

iris — validate landing.yaml

  [OK] landing.yaml is valid

Catches missing required fields, files that don't exist, and models not pulled in Ollama.

---

iris history

Shows a log of all past runs.

iris history

iris — history

  [1] 2026-05-15 14:32 — landing.yaml
      Model:   qwen2.5-coder:7b
      Changed: src/App.jsx, src/App.css

  [2] 2026-05-15 15:10 — logic.yaml
      Model:   qwen2.5-coder:7b
      Changed: src/main.jsx

---

iris status

Shows the current project path, profile, Ollama status, and last run info.

iris status

iris — status

  Project:   C:/Users/user/projects/my-app
  Profile:   web
  Model:     qwen2.5-coder:7b
  Ollama:    running ✓
  Last run:  2 file(s) changed
  Backup:    available (iris undo to restore)

---

iris start

Opens the TUI (Text User Interface) — navigate with arrow keys, select with Enter.

iris start

┌────────────────────────────────────┐
│  ▶ INIT                            │
│    RUN                             │
│    VALIDATE                        │
│    STATUS                          │
│    HISTORY                         │
│    UNDO                            │
│    EXIT                            │
└────────────────────────────────────┘

---

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 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 iris_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

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

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

---

functions — function-level access control

Limit the agent to specific functions only. The rest of the file stays untouched.

access:
  write:
    - Assets/Scripts/HealthSystem.cs:
        functions:
          - TakeDamage
          - Heal
          - Die

    - Assets/Scripts/PlayerStats.cs:
        functions:
          - AddExperience
          - LevelUp
        forbidden_functions:
          - ResetAllProgress
          - DeleteSave

• functions — agent can only read and modify these functions
• forbidden_functions — agent must never touch these functions

Supported languages: Python, JavaScript, TypeScript, C#, Java, Go, C, C++, Kotlin.

---

backup + iris undo — rollback support

When backup: true, the original contents of all write files are saved to iris_report.yaml before any changes are made. Run iris undo to restore everything.

---

Report format

When feedback: true, Iris writes iris_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
• Modify functions listed in forbidden_functions

---

Roadmap

v1.6

• iris init, run, undo, status
• model parameter
• error parameter
• reference parameter
• instructions as a list
• iris undo — rollback from backup

v1.7

• iris run a.yaml b.yaml — run multiple instructions at once
• iris history — view past runs
• iris validate <file.yaml> — check YAML syntax before running
• functions: — function-level access control

v1.8

• TUI interface — iris start
• Project profiles in INIT (unity, web, python, cli, custom)
• pip install iris-dev

v1.8.3 — current

• Fixed functions parser — correct indentation and injection order

---

License

Iris 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 Iris by Anasteyshen and include a link to the original repository.

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.

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 "Iris" 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.