🤖 Agentists Quick Start

Welcome to the Agentists Quick Start repository - your opinionated guide to getting started with agentic engineering. 🚀

⚡ Quick Start

Launch a ready-to-use workspace in seconds using DevPod:

Motivation

• Share your set up across CodeSpaces and/or your HomeLab
  This includes:
• Favored VS Code extensions
• Shared secrets (e.g. Claude API Key e.g. ANTHROPIC_API_KEY) from an external provider such as Github Codespaces Secrets or 1password

Install DevPod in a Code space

• Clone this repo
• Create a codespace from it
• Install DevPod

  curl -L -o devpod "https://github.com/loft-sh/devpod/releases/latest/download/devpod-linux-amd64" && sudo install -c -m 0755 devpod /usr/local/bin && rm -f devpod

Note: This repository is currently in a deprecated state. The workspace branches mentioned below (workspace/basic, workspace/security, workspace/batteries-included, workspace/20251208) are not currently maintained on the remote repository. See the plan documentation (docs/plan/plan.md) for information about the fleet architecture rearchitecture efforts.

Basic Development Environment: (Currently not available - branch does not exist)

# devpod up https://github.com/jedarden/agentists-quickstart@workspace/basic

Security-Focused Environment: (Currently not available - branch does not exist)

# devpod up https://github.com/jedarden/agentists-quickstart@workspace/security

🧠 What is Agentic Engineering?

Agentic engineering is the practice of building, deploying, and managing AI agents that can autonomously perform tasks, make decisions, and interact with various systems. This repository provides best practices and ready-to-use configurations to accelerate your journey into this emerging field.

📋 Prerequisites

For DevPod.sh (Recommended):

• DevPod CLI
• Docker Desktop or Docker Engine

For Manual Setup:

• Docker or Podman installed
• VS Code with Dev Containers extension
• Git
• Basic understanding of containerization

🛠️ Alternative Setup Methods

Manual VS Code Setup

Note: The workspace branches mentioned below are not currently available on the remote repository. This repository is in a deprecated state while fleet architecture reorganization is in progress.

1. Clone the repository

   git clone https://github.com/jedarden/agentists-quickstart
   cd agentists-quickstart
   

2. Check available branches

   git branch -a
   

3. Open in VS Code

   • Open the folder in VS Code
   • Install the Dev Containers extension if needed
   • If a workspace branch becomes available, click "Reopen in Container" when prompted

4. Refer to plan documentation

   • See docs/plan/plan.md for information about the fleet architecture and planned workspace branches

🎯 Core Principles

1. 🌐 Remote-First Development

All coding is performed remotely in isolated environments. No running on local.

• Use containerized development environments (DevPods)
• Ensures consistency across team members
• Eliminates "works on my machine" issues
• Provides clean separation between development and personal environments

2. 🏗️ Agent-Centric Architecture

Design systems with autonomous agents as first-class citizens.

• Build modular, composable agent components
• Implement clear agent boundaries and responsibilities
• Use standardized communication protocols between agents
• Design for scalability from single agent to multi-agent swarms

3. 📈 Continuous Learning and Adaptation

Agents should evolve and improve through interaction and feedback.

• Implement feedback loops for agent performance
• Use versioning for agent behaviors and models
• Track agent decisions and outcomes for analysis
• Enable A/B testing of agent strategies

📁 Repository Structure

This repository uses a branch-based approach for different DevPod configurations. Note: This repository is currently in a deprecated state while workspace branches are being reorganized.

Current Main Branch:

• main - Documentation and project overview

Historical Workspace Branches:
The following workspace branches have been referenced in documentation but are not currently maintained on the remote:

• workspace/basic - General-purpose development environment with Docker-in-Docker (not currently available)
• workspace/security - Security research environment with Node.js tools (not currently available)
• workspace/batteries-included - Fleet-capable environment with tmux NATO naming and advanced tooling (not currently available)
• workspace/20251208 - Legacy tmux fleet environment with MANA integration (not currently available)

Documentation:

• docs/plan/plan.md - Comprehensive plan for fleet architecture rearchitecture, including ADR-001 through ADR-004
• docs/notes/legacy-tmux-fleet.md - Documentation of the legacy tmux NATO fleet architecture

See the plan documentation for information about the ongoing fleet architecture reorganization efforts, including the transition from tmux-based to zellij/herdr-based fleet management.

🐳 DevPods

DevPods are our implementation of containerized development environments. Each DevPod is available as a separate branch that can be instantly launched using DevPod.sh.

Available DevPods:

Note: The batteries-included and 20251208 branches contain the legacy tmux-based fleet architecture. See Fleet Architecture Reorganization below for the transition plan to the new herdr-based fleet.

Benefits:

• 🚀 Instant workspace setup
• 🔒 Isolated environments
• 📦 Pre-configured tools
• 🤝 Consistent across teams

Fleet Architecture Reorganization

This repository is transitioning from a tmux-based fleet architecture to a herdr-based multiplexer for running multiple AI agents concurrently.

Current State

The legacy tmux fleet (available on workspace/batteries-included and workspace/20251208 branches) includes:

• NATO-named sessions: Each agent runs in a separate tmux session (alpha, bravo, charlie, …)
• Fleet launcher (start.sh): Automatically assigns the next available NATO name
• MANA integration: Tool-use governance and session tracking via PreToolUse hooks
• ccdash: Claude Code dashboard for fleet monitoring
• Tool set: claude-code, gh, kubectl, tmux, resurrect plugins

See docs/notes/legacy-tmux-fleet.md for complete details on the tmux architecture.

Transition Plan (ADR-002)

The project is adopting herdr, a maintained multiplexer that provides:

• Glanceable status signals: See at a glance which agents need human attention (🙋 indicators)
• Multi-agent support: Run Claude Code, Codex, and other agent CLIs in the same fleet
• Spaces → Tabs → Panes: Hierarchical organization matching the fleet model
• Better context detection: Reliable agent-state tracking without manual inspection

The transition plan is documented in docs/plan/plan.md, including:

• ADR-001: Original decision to adopt zellij (now superseded)
• ADR-002: Decision to adopt herdr instead of custom zellij implementation
• ADR-003: Correction on herdr's push-status API capabilities
• ADR-004: Multi-agent fleet support (Claude + Codex, one kind per pane)

Future Workspace Branch

Once the transition is complete, a new workspace/herdr branch will be published as the recommended fleet workspace, and the tmux-based branches will be marked as legacy.

✅ Best Practices

1. Always develop in containers - Never install development dependencies on your local machine
2. Document your agents - Clear documentation of agent capabilities and limitations
3. Test agent interactions - Implement comprehensive testing for multi-agent scenarios
4. Monitor agent behavior - Use logging and observability tools
5. Version everything - Agent code, configurations, and training data

🤝 Contributing

We welcome contributions! Please ensure:

1. All code is developed within a DevPod
2. Follow the established patterns and principles
3. Include documentation for new features
4. Test thoroughly before submitting

🗺️ Future Roadmap

• Agent templates and scaffolding tools
• Multi-agent orchestration examples
• Performance monitoring dashboards
• Agent communication protocols
• Security best practices guide

📄 License

Licensed under the MIT License.

Copyright 2025-2026 Jed Arden and contributors. See NOTICE for
attribution. By submitting a contribution, you agree to license it under the
MIT License as described in CONTRIBUTING.md.

💬 Support

For questions and support:

• Open an issue in this repository
• Check existing documentation
• Join our community in GitHub Discussions

Remember: The future of software development is agentic. Start building with the right foundation! 🏆