Copier Template for NiceGUI Agentic Applications

A standalone copier template for creating agentic AI assistants with NiceGUI web interfaces and Claude Code CLI integration.

Overview

This template generates a complete web application that:

• Uses NiceGUI for a modern, reactive web interface
• Integrates Claude Code CLI as the agentic orchestrator (via CBORG LBL service or Anthropic API)
• Supports MCP servers for custom tools (literature retrieval, web search, etc.)
• Provides real-time streaming responses and status updates
• Includes Python best practices (pyproject.toml, ruff linting, pytest)

Architecture

┌─────────────────────────────────┐
│   NiceGUI Frontend              │
│   - Real-time chat interface    │
│   - Stream responses            │
│   - Material Design UI          │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│   FastAPI Backend (built-in)    │
│   - Spawns claude CLI process   │
│   - Passes queries via stdin    │
│   - Streams stdout back to UI   │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│   Claude Code CLI               │
│   via CBORG (LBL) or Anthropic  │
│   + MCP servers for tools:      │
│   - artl-mcp (literature)       │
│   - mcp-server-fetch (web)      │
│   - Custom domain tools         │
└─────────────────────────────────┘

Quick Start

Prerequisites

• Python >= 3.11
• uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
• copier (uv tool install copier --with jinja2-time)
• Claude Code CLI (for running the agent)

Generate a New Project

copier copy --trust gh:Knowledge-Graph-Hub/nicegui-app-copier my-agent-app

You'll be prompted to answer questions about your project:

• Project name and description
• Author information
• License
• API configuration (CBORG vs. Anthropic)
• Which MCP servers to include
• Port number

Run Your App

cd my-agent-app

# Set up API keys
export ANTHROPIC_AUTH_TOKEN=$(cat ~/cborg.key)
export ANTHROPIC_BASE_URL=https://api.cborg.lbl.gov
export ANTHROPIC_MODEL=anthropic/claude-sonnet

# Install dependencies
uv sync

# Run the app
python app.py

Open browser to http://localhost:8080

What Gets Generated

my-agent-app/
├── app.py                    # NiceGUI application entry point
├── agent_alz_assistant/      # Python package
│   ├── __init__.py
│   └── agent.py             # Claude CLI orchestrator
├── pyproject.toml           # Dependencies and project config
├── mcp_config.json          # MCP server configuration
├── CLAUDE.md                # System prompt for the agent
├── README.md                # Project-specific README
├── .env.example             # Environment variable template
└── .gitignore

Customization

System Prompt

Edit CLAUDE.md to customize how your agent behaves:

# My Agent Instructions

You are a specialized assistant for [domain].

## Your Capabilities
- Tool 1: Description
- Tool 2: Description

## Guidelines
- Be helpful and clear
- Cite sources
...

MCP Servers

Edit mcp_config.json to add/remove tools:

{
  "mcpServers": {
    "my-tool": {
      "command": "uvx",
      "args": ["my-mcp-server"]
    }
  }
}

API Configuration

The template supports two modes:

CBORG (LBL service to provide access to LLMs)

export ANTHROPIC_AUTH_TOKEN=your-cborg-key
export ANTHROPIC_BASE_URL=https://api.cborg.lbl.gov
export ANTHROPIC_MODEL=anthropic/claude-sonnet

Direct Anthropic API

export ANTHROPIC_AUTH_TOKEN=your-anthropic-key
export ANTHROPIC_MODEL=claude-sonnet-4-20250514

Default MCP Servers

The template can include:

1. artl-mcp - Scientific literature retrieval by DOI/PMID/PMCID

   • Fetches full text from PubMed, arXiv, and other sources

2. mcp-server-fetch - Web content fetching

   • Retrieves and processes web pages

Both are optional and can be enabled/disabled during project generation.

Examples

• agent-alz-assistant - Alzheimer's research assistant

Development

The generated project includes:

Run tests:

uv run pytest

Lint code:

uv run ruff check .

Format code:

uv run ruff format .

Non-Interactive Generation

Use a YAML file for automation:

# my-answers.yaml
project_name: my-agent-app
project_slug: my_agent_app
project_description: My agentic assistant
email: [email protected]
full_name: Your Name
use_cborg: true
include_artl_mcp: true
include_fetch_mcp: true

copier copy --trust --defaults --data-file my-answers.yaml \
  gh:Knowledge-Graph-Hub/nicegui-app-copier my-agent-app

Relationship to monarch-project-copier

This template is inspired by monarch-project-copier and follows similar patterns (copier.yaml structure, jinja templates, etc.) but is standalone and focused on NiceGUI web applications rather than LinkML schemas.

If you need more comprehensive project infrastructure (CI/CD, documentation generation, advanced testing), consider using monarch-project-copier and manually adding the NiceGUI app files.

Contributing

Contributions welcome! This template is designed to evolve with best practices for agentic AI applications.

License

BSD-3-Clause