Skip to main content

Quick Start

Get started with Amux in minutes.

Workspace Basics​

1. Initialize Amux​

Navigate to your project and initialize Amux:

cd your-project
amux init

This creates a .amux/ directory to store workspace metadata. You'll be asked if you want to add .amux/ to your .gitignore file to keep workspace data out of version control.

2. Create a Workspace​

amux ws create feature-auth

You now have an isolated Git worktree ready for development!

3. List Your Workspaces​

amux ws list

Output:

ID  NAME          BRANCH                           CREATED
1   feature-auth  amux/workspace-feature-auth-...  2 minutes ago

Working with AI Agents​

If you have AI agents configured, you can run them in your workspaces:

4. Run an AI Agent​

amux run claude --workspace feature-auth

5. List Sessions​

Check your running AI agents:

amux ps

Output:

ID  NAME     AGENT   WORKSPACE     STATUS
1   sess-1   claude  feature-auth  🟢 running

6. Attach to AI Agent​

Connect to your running AI agent for interactive work:

amux attach 1  # Use session ID from 'amux ps'

Exit the session with Ctrl+B then D (detach) or exit (terminate).

What You've Achieved​

Workspace Setup​

✅ Initialized Amux in your project ✅ Created an isolated workspace for feature development ✅ Learned how to manage multiple workspaces

AI Agent Integration (if completed)​

✅ Started an AI agent in an isolated environment ✅ Monitored running sessions ✅ Connected to your AI agent for interactive work

You're now ready to run multiple AI agents in parallel without conflicts!

Next Steps​