Claude Agents Launcher

This package provides an interactive launcher for Claude Code agent sessions with predefined personas, configurations, and project templates.

Generating the Docker-ready Tarball

To bundle everything into a portable, standalone tarball (.tgz) for installation anywhere (including lightweight Docker images without development tools):

1. Build and pack the project:

   npm pack

   This automatically compiles the TypeScript source into a standard Node compatible Javascript format and bundles everything into something like claude-agents-1.0.0.tgz.

Installing and Running in Docker

You can copy the generated .tgz archive to your Docker container and install it globally via npm. Here is an example Dockerfile snippet showing how you would install it:

# Start from your preferred Node.js image
FROM node:20-alpine

# Set the working directory
WORKDIR /app

# Copy the bundled agents tarball generated by npm pack into the image
COPY claude-agents-1.0.0.tgz .

# Install the tarball globally so the CLI command is available system-wide
RUN npm install -g ./claude-agents-1.0.0.tgz

# (Optional) Verify that the command is available
RUN agent --help || true

# Any other setup...

Running the Agent

With the package installed globally in the container, you can run the launcher from any directory by simply calling:

agent

When you start the agent, it will launch an interactive CLI that will prompt you to:

1. Select a Config (behavior & standards)
2. Select a Persona (agent role & expertise)
3. Select a Mode:
   • Interactive: Starts a standard claude chat session populated with the chosen persona and config context.
   • One-shot: Asks for a specific Task, passes it to Claude, runs to completion, and then exits automatically.

Automated/Non-Interactive Execution

If you want to use this launcher from another automation script or bypass the interactive prompts entirely, you can pass your selections directly as CLI flags:

agent --config="strict" --persona="automation-expert" --mode="one-shot" --prompt="Build a deployment bash script"

Or use positional arguments for the prompt:

agent --config="strict" --persona="automation-expert" --mode="one-shot" Build a deployment bash script

Available flags:

• --config=<name>: The behavior config to use (e.g., default, strict, creative).
• --persona=<name>: The persona to adopt (e.g., backend-rest, react-expert).
• --mode=<mode>: Set to interactive or one-shot.
• --prompt=<text>: The task to run (only used if mode is one-shot).

If you omit any of these flags, the CLI will interactively ask you for the missing information.

Environment Variables

If you choose to run the tool from a directory or installation method where it cannot automatically find the personas, configs, and projects folders, you can explicitly map them to an absolute path by defining the following environment variable:

export CLAUDE_AGENTS_DIR=/path/to/extracted/agents/data