Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (90 loc) · 5 KB

AGENTS.md

File metadata and controls

124 lines (90 loc) · 5 KB
Raw

Agents entry point

Project overview

Zikon is a developer utility that generates web icons and visual assets via a diffusion model pipeline and converts them to SVG. It is designed to be invoked by AI agents mid-task and can be installed locally as a reusable CLI.

Pipeline summary

prompt → generate.py (diffusers) → PNG → trace.js (imagetracerjs) → SVG + JSON

Script layout

Python scripts are grouped under scripts/, each as a standalone uv project. The Node.js orchestrator and installer live under cli/:

Path Purpose
scripts/generate/ PNG generation — Python + diffusers + torch
scripts/trace/ PNG → SVG tracing — Node.js + imagetracerjs
cli/ Unified CLI orchestrator and installer — Node.js + commander

Key files

File Purpose
cli/zikon.js Unified CLI entry point — orchestrates PNG + SVG pipeline and implements zikon install
cli/package.json Node.js project manifest (commander dependency)
scripts/generate/generate.py Python CLI — generates PNG from prompt
scripts/generate/diffusers_backend.py Real diffusers+torch pipeline
scripts/generate/stub_backend.py Stdlib-only fallback (no torch required)
scripts/generate/pyproject.toml uv project manifest
zikon-skills/SKILL.md Installable skill for Claude Code / compatible agents — install with npx skills add https://github.com/quinteroac/zikon/zikon-skills, invoke with /zikon "<prompt>"

CLI interface

Unified CLI (current):

node cli/zikon.js "<prompt>" [--model z-image-turbo|sdxl|<hf-repo>] [--output-dir <path>] [--style <hint>] [--seed <int>] [--size <px>[,<px>...]]

Installer command (current):

node cli/zikon.js install [--installation-path <path>]

Installed command (after zikon install):

zikon "<prompt>" [--model z-image-turbo|sdxl|<hf-repo>] [--output-dir <path>] [--style <hint>] [--seed <int>] [--size <px>[,<px>...]]

Python generate script (standalone):

cd scripts/generate
uv run generate.py --prompt <text> --model <z-image-turbo|sdxl|hf-repo/name> --output <path.png> [--steps <int>] [--seed <int>]

Output is always a single JSON object on stdout:

{
  "prompt": "minimalist rocket icon",
  "model": "z-image-turbo",
  "seed": 42,
  "png_path": "/abs/path/output/minimalist_rocket_icon.png",
  "svg_path": "/abs/path/output/minimalist_rocket_icon.svg",
  "svg_inline": "<svg xmlns=\"http://www.w3.org/2000/svg\">...</svg>"
}

Exit codes: 0 success · 1 PNG generation error · 2 SVG tracing error · 3 invalid arguments.

Output filename convention:

  • Single size equal to the default (1024): file is named <slug>.svg (no size suffix) for backward compatibility.
  • Any other single size or multiple sizes: files are named <slug>_<size>.svg (e.g. minimalist_rocket_icon_512.svg).

Release checklist for documentation changes:

Before merging any update to README.md, AGENTS.md, or .agents/PROJECT_CONTEXT.md, manually verify that the file renders correctly in a Markdown renderer (e.g. GitHub preview or a local renderer) — satisfying US-005-AC04.

Installation behavior

  • Default install directory: ~/.zikon on Linux/macOS and %USERPROFILE%\\.zikon on Windows
  • Custom install directory: pass --installation-path <path>
  • Installer copies cli/, scripts/generate/, and scripts/trace/ into the target directory
  • Installer runs uv sync, installs the selected PyTorch backend, and installs Node dependencies for both cli/ and scripts/trace/
  • Installer creates the executable shim in bin/ (zikon on Unix, zikon.cmd on Windows)
  • On Unix-like systems, the installer updates ~/.bashrc and ~/.zshrc; on Windows it prints manual PATH instructions

Skill installation and invocation

The Zikon skill is defined in zikon-skills/SKILL.md. Install it with:

npx skills add https://github.com/quinteroac/zikon/zikon-skills

Then invoke it from any compatible agent:

/zikon "rocket icon"
/zikon "coffee cup logo" --model sdxl --style "flat minimal" --output-dir ./assets

Agent instructions

  • If Zikon is not installed yet, run node cli/zikon.js install first from the repository checkout.
  • Always pass --output-dir to avoid writing to the current working directory.
  • Use --model z-image-turbo for fast iteration, --model sdxl for final output.
  • Parse svg_inline from the JSON response to embed the SVG directly in markup.
  • Do not retry on exit code 1 without changing the prompt — the model error is likely deterministic for that input.

Tech stack

  • Python 3.11+ + diffusers + torch + accelerate + Pillow — image generation
  • uv — dependency management; each script group has its own pyproject.toml
  • Node.js + imagetracerjs — SVG tracing (scripts/trace/)
  • Bun — cross-platform packaging target for distributable installer builds
  • No external API calls — all inference runs locally

Current iteration

See ROADMAP.md.