hauschi86/claudenius-studio repository overview

⁠claudenius-studio

A fully autonomous AI agent container powered by Claude Code and Gemini CLI. Ships with 6 creative tools, a broad set of language runtimes (Java, Node.js, Python, Go, C/C++), a web terminal, and a built-in File Browser — ready to build software, generate documents, process media, and deploy containers from any browser.

⁠Table of Contents

• Quick Start⁠
• With Docker Compose (recommended)⁠
• How Your Project Is Organized⁠
  • What your project looks like⁠
  • Your customizations — .claudenius-setup/⁠
  • Your data — .claudenius-data/⁠
  • Runtime files (gitignored)⁠
  • Customizing agent instructions⁠
  • Adding a technology-stack file⁠
  • Overriding skills⁠
  • Migrating from an older release⁠
• What's Inside⁠
• Image default + bundles override⁠
• Ports⁠
• Docker Access⁠
• Git Persistence⁠
• Paste & drop files into the terminal⁠
• What The Agent Can Do⁠
• Architecture⁠
• Supported Platforms⁠

⁠Quick Start

docker run -d \
  --name ai-agent \
  -p 14000:14000 \
  -p 14002-14100:14002-14100 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  hauschi86/claudenius-studio:latest

Open http://localhost:14000⁠ in your browser for the web terminal. A File Browser is available at http://localhost:14002⁠ (default credentials: admin/admin) for browsing and downloading files the agent creates.

Authenticate and start an agent:

# Claude Code
claude auth login
claude --dangerously-skip-permissions

# Gemini CLI
gemini          # will ask you to log in on first run
gemini -y       # YOLO mode — auto-approves actions

⁠With Docker Compose (recommended)

The easiest way is to download the bundle ZIP for the latest release and unzip it in your project root:

unzip claudenius-studio-<version>-minimal.zip

# Easiest — run the shipped launcher (no Docker knowledge required):
./start.sh        # Linux / macOS
start.bat         # Windows  (double-click also works)

# Or directly:
docker compose up -d

The bundle ships docker-compose.yml, .env, .gitignore, start.sh, start.bat, and a .claudenius-setup/ skeleton with working defaults (port 14000). Release bundles also pre-pin the image version in .env so docker compose up always gets the matching release. Edit .env if you need a different port, image tag, or want to enable Git persistence.

The bundle's docker-compose.yml is static and safe to commit — it defines the claude-agent + postgres services, maps ports 14000 (terminal), 14002 (File Browser) and 14003-14100 (apps), mounts your project as /workspace plus the Docker socket, and reads all settings from a gitignored .env:

.env (your actual values):

HOST_PORT_BASE=14000
DB_PORT=14001
FB_PORT=14002
APP_PORT_START=14003
APP_PORT_END=14100
FILEBROWSER_USER=admin
FILEBROWSER_PASSWORD=admin
# Release bundles ship IMAGE_TAG=<version> uncommented; SNAPSHOT bundles leave
# it commented and the compose file falls back to :latest.
IMAGE_TAG=1.5.1
#GIT_REPO=https://github.com/your-org/your-repo.git
#GIT_TOKEN=your-token-here

Docker Compose reads .env automatically — no extra flags needed.

⁠How Your Project Is Organized

Your project folder is the workspace. The single volume mount .:/workspace means the agent works directly inside your repo — no subfolders, no syncing. You see the agent's files in your IDE in real-time, and the agent sees your code instantly.

All claudenius-specific directories use a dot-prefix (.claudenius-*) so they stay out of the way — just like .git/ does.

⁠What your project looks like

After unzipping the bundle and starting the container:

my-project/                         ← your git repo root = /workspace
│
│   YOUR CODE (untouched)
├── src/                            ← your source code
├── package.json                    ← your project files
├── docker-compose.yml              ← starts the container (safe to commit)
├── .env                            ← secrets: ports, git tokens (gitignored)
├── start.sh / start.bat            ← shipped launcher scripts (one per OS)
│
│   CUSTOMIZATION (checked into git — you manage these)
├── .claudenius-setup/
│   ├── context/                    ← custom agent instructions (.md files merged into CLAUDE.md)
│   │   └── 00-project.md          ← sample: your project-specific rules
│   ├── skills/                     ← override built-in skill definitions
│   ├── agents/                     ← native Claude Code subagent files (<role>.md with YAML frontmatter)
│   └── agent-team/                 ← non-prompt team docs (workflow.md etc.)
│
│   DATA (shared — agent writes here, you can add files too)
├── .claudenius-data/
│   ├── diagrams/                   ← /mermaid output
│   ├── captures/                   ← /playwright screenshots & PDFs
│   ├── scripts/                    ← generated scripts (.ts, .js, .py)
│   ├── media/                      ← /ffmpeg video & audio
│   ├── images/                     ← /imagemagick output
│   ├── presentations/              ← /python-pptx .pptx files
│   ├── drops/                      ← files you paste/drag-drop into the terminal (gitignored)
│   ├── startup.log                 ← full container-startup log (verify skill/agent sync)
│   ├── backups/<timestamp>/files/  ← snapshot of .claude taken before each start's merge (gitignored)
│   └── (your files)                ← drop CSVs, images, docs here for the agent
│
│   RUNTIME (gitignored)
├── .claude/                        ← Claude Code state: skills/agents MERGED in place (never wiped; newest wins). Other files reassembled each start.
├── .claudenius/                    ← symlinks to tools inside the image (recreated each start)
├── CLAUDE.md                       ← assembled agent instructions (recreated each start)
├── WELCOME.md                      ← agent greeting (recreated each start)
└── .gitignore                      ← keeps auto-generated files out of git

⁠1. Your customizations — .claudenius-setup/

This is how you control the agent. Everything in this folder is checked into git and survives container restarts. It has up to four subdirectories:

You don't need to use all of them — most users only need context/.

⁠2. Your data — .claudenius-data/

One folder for everything — files the agent generates AND files you want the agent to use.

Example: cp sales-report.csv .claudenius-data/, then ask the agent to "create a bar chart from sales-report.csv" — it writes the PNG to .claudenius-data/images/, which you open from your IDE or File Browser.

The subdirectories (diagrams/, images/, media/, etc.) are created automatically at startup; you can add your own folders or drop files anywhere inside.

It also holds three runtime helpers (all gitignored): startup.log — a fresh per-boot record of which skills/agents were installed, updated, or kept, plus the CLAUDE.md assembly trace; backups/<timestamp>/files/ — a snapshot of .claude/ taken before each start's merge (only when changed; restore from here if a merge ever overwrites something); and drops/ — files you paste/drag-drop into the terminal (see below).

⁠3. Runtime files (gitignored)

Most of these are reassembled every start — don't edit them directly. The exception is .claude/skills/ and .claude/agents/: they're merged in place, never wiped — existing/live-added files survive, and on a name clash the newest mtime wins. .claudenius-setup/.skip-default (shipped by every bundle) makes the entrypoint ignore baked context + agent defaults; skills always merge.

.claudenius/, CLAUDE.md, and WELCOME.md are safe to delete (they reappear next start). A skill/agent deleted from .claude/ only returns if it also exists in a source; live-only additions stay gone. Every decision is logged to .claudenius-data/startup.log.

⁠Customizing agent instructions

The agent's instructions (CLAUDE.md) are assembled at startup by merging files from two sources:

1. Image defaults at /opt/claudenius/defaults/context/ — baked into the image so a bare docker run yields a working Java/Angular agent. Skipped if .claudenius-setup/.skip-default is present.
2. Your .claudenius-setup/context/ — overlays the defaults; same-named files replace the default; new files are inserted by sort order.

Bundle ZIPs always ship .claudenius-setup/.skip-default, so when you unzip a bundle the image defaults are skipped entirely and CLAUDE.md is built only from the bundle's files. The bundle is hermetic: what you see in .claudenius-setup/context/ is exactly what the agent reads.

Baseline files (shipped in every bundle's .claudenius-setup/context/, also baked at the image's default-context path):

How merging works:

1. Every .md file in .claudenius-setup/context/ is included.
2. Files are sorted by filename and concatenated into CLAUDE.md.
3. To customize, edit the baseline files in place, add new ones (e.g. 45-my-rules.md), or delete the ones you don't want.

Example: drop a 45-testing.md into .claudenius-setup/context/ with your rules and restart — the 45- prefix places it between 40-… and 50-environment.md in sort order.

⁠Adding (or replacing) a technology-stack file

The image's default 40-stack.md is the Quarkus + Angular ruleset. The java-angular bundle ships the same content. To replace it with your own stack, drop a 40-stack.md into .claudenius-setup/context/. Because every bundle ships .skip-default, your file is the only 40-stack.md the agent sees — no merging with the baked default.

To drop the stack altogether (let the agent pick freely per task), use the minimal bundle (which ships no 40-stack.md) — .skip-default ensures the image's default 40-stack.md is also ignored.

To write your own stack rules, put your mandatory tech choices (frameworks, build tools, conventions) into .claudenius-setup/context/40-stack.md.

⁠Overriding skills

Skills are slash-commands like /mermaid, /playwright, /ffmpeg. Each skill is a SKILL.md file that tells the agent how to use that tool. Unlike context, skills are baked into the image (they're tightly coupled with the binaries the image ships).

To override a built-in skill, recreate the same folder under .claudenius-setup/skills/ (e.g. .claudenius-setup/skills/mermaid/SKILL.md) with your own SKILL.md.

At startup your version is merged into .claude/skills/. Existing files in .claude/ are never deleted, and on a name clash the newest copy wins — so editing your setup skill takes effect on the next start, and a skill you create directly in .claude/skills/ survives restarts. Skills you don't override keep their defaults; every decision is logged to .claudenius-data/startup.log.

⁠Migrating from an older release

Bundles ship .claudenius-setup/.skip-default, so the unzipped tree is the complete truth (image defaults skipped). To upgrade: re-download the latest bundle and unzip into your project root — files you've customized are preserved; new baseline files are added in sort order.

⁠What's Inside

⁠Creative Tools

⁠Languages & Runtimes

Framework CLIs (Quarkus, Angular CLI, etc.) are installed unconditionally so any bundle that opts into them works out of the box, but the image itself doesn't promote any specific framework.

⁠Agent Teams

Claude Code agent teams⁠ are enabled by default (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). This lets you orchestrate multiple Claude Code instances working together — a lead agent coordinates teammates, each running in its own context window with shared task lists and direct messaging. No manual setup needed.

The Docker image itself ships no agent definitions — they come from the use-case bundle you unzip. The java-angular bundle ships a 5-agent team (lead, backend, frontend, reviewer, tester) as native Claude Code subagent files under .claudenius-setup/agents/, plus a workflow/protocol document at .claudenius-setup/agent-team/workflow.md. The lead orchestrates via Agent({subagent_type: 'backend'}) etc.; subagent prompts load automatically. To create your own roles, drop more <role>.md files into .claudenius-setup/agents/ (YAML frontmatter with name, description, optional tools and model).

⁠Paste & drop files into the terminal

You can paste (Ctrl+V) or drag-and-drop files directly onto the web terminal — images, PDFs, CSVs, logs, anything — and have the agent read them. The browser terminal is served through a small proxy that captures the file in the browser, saves it to .claudenius-data/drops/, and types a filedrop token into your prompt. A toast confirms where each file landed.

In a claude session, just paste or drop your file(s) and ask:

filedrop what does this screenshot show?
filedrop analyse the last 3 PDFs I dropped

A UserPromptSubmit hook (installed automatically) expands filedrop into a newest-first list of your recent drops and points Claude at the relevant file(s) — the Read tool renders images visually and reads text/PDF as content. Multiple files in one paste/drop are supported. Dropped files live in .claudenius-data/drops/ (gitignored).

⁠Developer Tools

GitHub CLI (gh), Gemini CLI, Docker CLI + Compose, git-lfs, shellcheck, pandoc, jq, yq, sqlite3, PostgreSQL/MySQL clients

⁠Image default + bundles override

The image bakes a Quarkus + Java + Angular default stack (the 5-agent dev team, the 9 baseline rules, the 40-stack ruleset). Run docker run hauschi86/claudenius-studio:latest and the agent is ready for full-stack Java/Angular work with no setup.

To use a different stack — or no stack at all — unzip a bundle ZIP. Every bundle ships .claudenius-setup/.skip-default, which tells the entrypoint to ignore image defaults entirely; the bundle's .claudenius-setup/ becomes the complete truth.

Other bundles (python-fastapi, react-frontend, etc.) can be added by following the recipe in bundles/assembly/README.md in the source repo. They get the same .skip-default treatment automatically.

Skills are exempt from skipping — /mermaid, /playwright, /ffmpeg, etc. always merge from image defaults regardless of .skip-default, because they're tightly coupled to the binaries the image ships.

⁠Ports

⁠Custom Port Range (HOST_PORT_BASE)

By default, the container's internal ports (14000-14100) are mapped 1:1 to the host. If you need a different host port range — for example, to run multiple instances or avoid conflicts — set HOST_PORT_BASE:

# Example: map to host ports 22000-22100
services:
  claude-agent:
    ports:
      - "22000:14000"
      - "22002-22100:14002-14100"
    environment:
      HOST_PORT_BASE: "22000"

The agent reads HOST_PORT_BASE and automatically adjusts the URLs it gives you. The File Browser at internal port 14002 becomes http://localhost:22002, and so on for all agent-launched services.

⁠Docker Access

The agent can build Docker images and manage containers on the host when the Docker socket is mounted. It has the Docker CLI and Docker Compose plugin pre-installed.

Security guardrails are enforced via CLAUDE.md (Claude Code's context file). The agent is instructed to never use --privileged, --pid=host, --net=host, or mount sensitive host paths (/, /etc, /var/run/docker.sock). It is also restricted from stopping or removing containers it didn't start, and from running destructive commands like docker system prune. These are soft guardrails — they rely on the AI model respecting its instructions, not on kernel-level enforcement.

⁠Git Persistence

Provide GIT_REPO and GIT_TOKEN environment variables to give the agent a Git repository for persisting its work. The agent commits and pushes changes automatically.

⁠What The Agent Can Do

• Build backend services in any installed language (Java, Node.js, Python, Go, C/C++) — framework choice follows the bundle you unzip
• Build frontend applications — framework choice follows the bundle (e.g. Angular with the java-angular bundle, or your own pick)
• Generate diagrams and presentations
• Process images, video, and audio
• Automate browsers for screenshots, scraping, and testing
• Build Docker images and deploy containers
• Install any additional tools or packages on demand (passwordless sudo)
• Start web servers accessible from the host on ports 14003-14100
• Browse and download generated files via the built-in File Browser (port 14002)
• Analyze files you paste or drag-and-drop straight into the terminal (filedrop — images, PDFs, CSVs, …)
• Connect to PostgreSQL and other databases
• Persist work via Git

⁠Architecture

Browser
    |
    +-- http://localhost:14000 --> ttyd (web terminal)
    +-- http://localhost:14002 --> File Browser (browse/download files)
    |
    v
  bash (agent user, passwordless sudo)
    |
    v
  Claude Code CLI / Gemini CLI
    |
    +-- 6 creative tools (Mermaid, Playwright, FFmpeg, ImageMagick, python-pptx, TypeScript)
    +-- Language runtimes: Java 21 + Maven, Node.js 24 + npm, Python 3, Go, C/C++
    +-- Framework CLIs (opt-in via bundles): Quarkus, Angular CLI
    +-- Docker CLI (host engine)
    +-- PostgreSQL (network)
    +-- Git (persistent storage)

⁠Supported Platforms

Docker automatically pulls the correct image for your platform.

⁠Base Image

node:24-bookworm (Debian 12)

⁠License

MIT