Iris

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

Version: v1.9.0

---

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.

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.

---

Installation

pip install iris-dev

Requirements: Python 3.10+, Ollama installed and running.

---

Quick Start

1. Launch Iris

iris start

This opens the TUI — a terminal interface where you can do everything without remembering commands.

    ██╗██████╗ ██╗███████╗
    ██║██╔══██╗██║██╔════╝
    ██║██████╔╝██║███████╗
    ██║██╔══██╗██║╚════██║
    ██║██║  ██║██║███████║
    ╚═╝╚═╝  ╚═╝╚═╝╚══════╝

  Copyright by Anasteyshen666   Version: 1.9.0

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

  ↑↓ navigate   Enter select   Ctrl+C exit

2. Initialize your project

Select INIT in the TUI, choose a profile and enter your project path.

Or use the CLI:

iris init

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. Profile: web

3. Write a YAML instruction

Create a file task.yaml in your project folder:

model: qwen2.5-coder:14b

access:
  write:
    - src/App.jsx
    - src/styles.css
  ban:
    - .env
    - src/auth.js

prompt: Add a dark mode toggle with CSS variables and localStorage

backup: true
feed: true

4. Run it

In the TUI select RUN, pick your yaml file and press Enter. Or via CLI:

iris run task.yaml

iris — running task.yaml

  [SYNTAX]   1.9
[1/4] Collecting context...
[2/4] Sending request to Ollama...
  [MODEL]    qwen2.5-coder:14b
  [TEMP]     0.1
[3/4] Applying changes...
  [WRITTEN]  src/App.jsx
  [WRITTEN]  src/styles.css
[4/4] Finalizing...
  [REPORT]   iris_report.yaml

iris — done (2 file(s) changed)

5. Something went wrong? Undo it.

iris undo

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

---

TUI Guide

Launch with iris start. Navigate with arrow keys, select with Enter.

Screen	Description
INIT	Set up project path and profile
RUN	Select one or multiple YAML files to run (Space to select, Enter to run)
VALIDATE	Check a YAML file for errors before running
STATUS	View current project, Ollama status, last run info
HISTORY	View past runs
MODELS	List installed Ollama models, add or delete models
UNDO	Roll back the last run

During a run — press Enter to stop execution immediately. No changes are saved.

---

YAML Syntax

New syntax (v1.9) — recommended

model: qwen2.5-coder:14b

access:
  read:
    - src/main.jsx
  write:
    - src/App.jsx
    - src/styles.css
  ban:
    - .env

prompt: Add a dark mode toggle

backup: true
feed: true

Minimum required:

access:
  write:
    - src/App.jsx

prompt: Add a dark mode toggle

Parameters

Parameter	Type	Required	Description
prompt	string	yes	What the agent should do
model	string	no	Ollama model (default: qwen2.5-coder:7b)
access.write	list	yes	Files the agent can modify or create
access.read	true / false / list	no	Files the agent can read for context
access.ban	list	no	Files the agent must never touch
ref	list	no	Example files for style reference
err	string	no	Console error to fix. Use console.msg to read from last captured output
feed	boolean	no	Save report with changes and tips
backup	boolean	no	Save original files before overwriting
temperature	float	no	Model temperature (default: 0.1)

Legacy syntax (pre v1.9) — still supported

task: "Add a dark mode toggle"
model: qwen2.5-coder:14b
access:
  read: true
  write:
    - src/App.jsx
  forbidden:
    - .env
instructions:
  - Add CSS variables for dark mode
  - Add toggle button to header
feedback: true
tips: true
backup: true

---

Function-level Access Control

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

New syntax:

access:
  write:
    - src/player.py:
        func:
          - take_damage
          - heal
        ban:
          - reset_all
          - delete_save

Legacy syntax:

access:
  write:
    - src/player.py:
        functions:
          - take_damage
          - heal
        forbidden_functions:
          - reset_all

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

---

Capturing Console Errors

Run your program through Iris to capture its output:

iris console python main.py

  [RUN] python main.py

  Traceback (most recent call last):
    File "main.py", line 12, in <module>
  NameError: name 'Workbook' is not defined

  [SAVED] Console output saved to iris_console.log
  [HINT]  Now use err: console.msg in your yaml

Then in your yaml:

access:
  write:
    - main.py

err: console.msg
prompt: Fix the error

---

Managing Models

In the TUI select MODELS to see all installed Ollama models, add new ones or delete unused ones.

Or via CLI:

ollama pull qwen2.5-coder:14b
ollama pull deepseek-coder-v2:16b

---

Commands

Command	Description
iris start	Open TUI
iris init	Initialize project
iris run <file.yaml>	Run instruction file
iris run a.yaml b.yaml	Run multiple files in sequence
iris undo	Roll back last run
iris validate <file.yaml>	Check YAML for errors
iris history	View past runs
iris status	View project status
iris console <command>	Run command and capture output

---

What the Agent Cannot Do

• Delete files
• Run shell commands
• Access files outside the project path
• Write files not listed in access.write
• Read files listed in access.ban
• Modify functions listed in ban inside write entries

---

Roadmap

v1.6 — v1.8.4

• Core CLI — init, run, undo, validate, history, status
• model, error, reference, instructions parameters
• backup + undo rollback
• TUI interface
• Project profiles
• Function-level access control
• pip install iris-dev
• System prompt + temperature control
• Fuzzy file name matching

v1.9 — current

• Redesigned TUI with ASCII logo and copyright
• MODELS screen — list, add, delete Ollama models
• Multi-select YAML in RUN (Space to select, Enter to run)
• Stop running agent with Enter
• New short syntax — prompt, feed, ref, err, func, ban
• Legacy syntax compatibility
• err: console.msg — read last console output automatically
• iris console <command> — capture program output
• yaml/ folder support for instructions
• History clears on new project
• Undo clears on new run

---