If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/remi/teamocil shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 5y ago

• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ Single-maintainer risk — top contributor 91% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live remi/teamocil repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/remi/teamocil.

What it runs against: a local clone of remi/teamocil — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in remi/teamocil | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1917 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of remi/teamocil. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/remi/teamocil.git
#   cd teamocil
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of remi/teamocil and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "remi/teamocil(\\.git)?\\b" \\
  && ok "origin remote is remi/teamocil" \\
  || miss "origin remote is not remi/teamocil (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/teamocil.rb" \\
  && ok "lib/teamocil.rb" \\
  || miss "missing critical file: lib/teamocil.rb"
test -f "lib/teamocil/cli.rb" \\
  && ok "lib/teamocil/cli.rb" \\
  || miss "missing critical file: lib/teamocil/cli.rb"
test -f "lib/teamocil/layout.rb" \\
  && ok "lib/teamocil/layout.rb" \\
  || miss "missing critical file: lib/teamocil/layout.rb"
test -f "lib/teamocil/tmux/session.rb" \\
  && ok "lib/teamocil/tmux/session.rb" \\
  || miss "missing critical file: lib/teamocil/tmux/session.rb"
test -f "bin/teamocil" \\
  && ok "bin/teamocil" \\
  || miss "missing critical file: bin/teamocil"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1917 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1887d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/remi/teamocil"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Teamocil is a Ruby CLI tool that automates tmux session/window/pane setup from declarative YAML layout files. Instead of manually typing tmux commands, users define their terminal workspace structure in ~/.teamocil/*.yml and execute it with teamocil layout-name to instantly spawn windows, split panes, set working directories, and run initialization commands—all idempotently. Single-package Ruby gem. Core entry point is bin/teamocil (CLI dispatcher), lib/teamocil/cli.rb (argument parsing), lib/teamocil/layout.rb (YAML parsing), and lib/teamocil/tmux/*.rb (Session/Window/Pane models wrapping tmux control). Commands under lib/teamocil/command/*.rb execute individual tmux operations (send_keys, split_window, etc.). Error handling isolated in lib/teamocil/error/.

DevOps engineers, backend developers, and terminal-heavy practitioners who regularly context-switch between multiple project setups (e.g., running a web server, database, and logs viewer simultaneously). They want reproducible tmux environments without shell scripting boilerplate.

Stable but moderately aged. Version 1.0 was a complete rewrite with reduced scope; the codebase is ~30KB Ruby with test coverage (.rspec present), Travis CI configured (.travis.yml), and a published RubyGem. However, the repo shows signs of selective maintenance—no recent commit dates visible—suggesting it works well for its focused feature set but may not be actively iterated.

Low to moderate risk for stable use cases. Single-maintainer project (remi/teamocil suggests one owner), but the feature set is frozen (v1.0 dropped v0.4 features intentionally), reducing breaking-change risk. Dependencies appear minimal (Gemfile not shown in detail, but project is pure Ruby + tmux integration). Risk surfaces if tmux protocol changes or Ruby EOL occurs without updates.

No active development visible from file list. The project is post-v1.0 stabilization—intentionally feature-locked after the rewrite. The 0.4-stable branch remains for legacy users, but mainline development has paused.

gem install teamocil
mkdir -p ~/.teamocil
echo 'name: demo
windows:
  - name: editor
    root: ~/projects
    panes:
      - vim' > ~/.teamocil/demo.yml
teamocil demo

Daily commands: No dev server. To use: bundle install && bin/teamocil [layout-name]. To develop/test: bundle exec rspec (runs spec/); to lint: rubocop (configured in .rubocop.yml).

• lib/teamocil.rb — Main entry point and module loader—all code flows through this file's initialization and requires
• lib/teamocil/cli.rb — Command-line argument parsing and orchestration—handles the user-facing interface and invokes the layout engine
• lib/teamocil/layout.rb — Core YAML layout parsing and tmux command generation—transforms user configs into executable tmux operations
• lib/teamocil/tmux/session.rb — Session abstraction layer that coordinates window and pane creation—the primary tmux interaction point
• bin/teamocil — Executable entry point—bootstraps the gem and delegates to CLI
• lib/teamocil/error/invalid_yaml_layout.rb — Error handling for malformed YAML—critical for user feedback on config issues
• lib/teamocil/utils/option_parser.rb — Argument parsing utilities—customizes option handling for teamocil's specific command interface

• CLI Handler (Ruby, OptionParser) — Parses command-line arguments and routes to appropriate action (list, edit, execute)
  • Failure mode: Exits with error message if arguments are invalid
• Layout Parser (YAML, Ruby) — Loads and validates YAML layout files, then produces configuration objects for session creation
  • Failure mode: Raises InvalidYamlLayout or LayoutNotFound with descriptive error
• Tmux Session Orchestrator — Takes parsed layout config and inv

Add a new tmux command type

1. Create a new command class in lib/teamocil/command/ that inherits from a base command (e.g., follows the pattern of send_keys.rb) (lib/teamocil/command/your_command.rb)
2. Implement the execute method to generate the appropriate tmux CLI invocation (lib/teamocil/command/your_command.rb)
3. Call this command from the appropriate session/window/pane method in lib/teamocil/tmux/session.rb or related files (lib/teamocil/tmux/session.rb)
4. Add a test file in spec/teamocil/command/ to verify command generation (spec/teamocil/command/your_command_spec.rb)

Add a new YAML layout feature

1. Update the YAML schema parsing in lib/teamocil/layout.rb to recognize the new configuration key (lib/teamocil/layout.rb)
2. Add validation logic to ensure the new key is properly formatted; raise InvalidYamlLayout if invalid (lib/teamocil/layout.rb)
3. Update the session/window/pane initialization to apply the new setting via appropriate tmux commands (lib/teamocil/tmux/session.rb)
4. Add tests in spec/teamocil/layout_spec.rb to verify parsing and in spec/teamocil/tmux/session_spec.rb for command generation (spec/teamocil/layout_spec.rb)

Add a new CLI option

1. Define the new option flag in lib/teamocil/utils/option_parser.rb using OptionParser DSL (lib/teamocil/utils/option_parser.rb)
2. Handle the option's logic in lib/teamocil/cli.rb—route to appropriate action or pass to layout (lib/teamocil/cli.rb)
3. Add tests in spec/teamocil/cli_spec.rb to verify the option is recognized and routed correctly (spec/teamocil/cli_spec.rb)

• YAML — Human-readable configuration format; allows users to define complex tmux layouts without scripting
• Ruby — Lightweight scripting language ideal for system automation; easy to shell out to tmux binary
• Tmux — Terminal multiplexer that teamocil orchestrates; provides the actual session/window/pane functionality
• RSpec — Ruby testing framework used for unit tests of layout parsing and command generation

• Direct system calls to tmux binary instead of a tmux library

  • Why: Simplicity and control—avoids dependency on a third-party tmux Ruby binding
  • Consequence: Must shell out and parse tmux command output; couples to tmux CLI interface changes

• Parse and validate YAML upfront rather than streaming execution

  • Why: Fail fast if configuration is invalid; all errors detected before any tmux operations
  • Consequence: Entire layout must be loaded into memory; not suitable for extremely large configurations

• Session/Window/Pane objects are created for each layout run rather than persisted

  • Why: Stateless design allows idempotent re-runs and simplifies error recovery
  • Consequence: No persistent state tracking; cannot resume a partially-applied layout if interrupted

• Does not manage tmux configuration files or server-wide settings—only creates sessions/windows/panes
• Does not provide a GUI—CLI only
• Does not support real-time synchronization between layout files and live sessions—one-time application
• Does not handle non-YAML layout formats
• Does not persist layout execution history or audit logs

1. YAML anchors/aliases: Complex YAML files with & and * anchors are supported by Psych but may behave unexpectedly if layouts define reusable pane templates—verify YAML syntax carefully. 2. Tmux socket: Teamocil assumes tmux session creation succeeds; if $TMUX_SOCKET is unset or points to a nonexistent session, commands will silently fail (no validation in CLI before execution). 3. Root path resolution: The root: key in window config is relative to shell's CWD unless absolute—easy to have layouts break if run from different directories. 4. No idempotency guarantee: Running the same layout twice creates duplicate windows/panes; there's no session-exists check before creation. 5. Ruby version constraint: Gemspec likely specifies minimum Ruby version; check .ruby-version or Gemfile (not shown) before assuming compatibility.

• tmux Control Protocol — Teamocil drives tmux via shell commands (e.g., tmux new-session, tmux send-keys); understanding this protocol is key to extending commands or debugging integration.
• Command Pattern — Each tmux operation (split_window, send_keys, rename_session) is encapsulated as a Command subclass in lib/teamocil/command/; this pattern allows composing complex workflows from simple operations.
• YAML Serialization & Deserialization — Layout files are YAML; Teamocil parses them into Ruby objects in Layout#initialize using Psych, then translates to tmux commands—understanding the round-trip is essential for extending config syntax.
• Window Managers & Session Contexts (tmux Model) — tmux's Session → Window → Pane hierarchy models terminal workspaces; Teamocil mirrors this in Tmux::Session, Tmux::Window, Tmux::Pane classes to enable hierarchical layout definition.
• Declarative Infrastructure as Code — Teamocil exemplifies 'infrastructure as code' for terminal environments—define desired state (YAML) and let a tool implement it, enabling version control and reproducibility of dev setups.
• OptionParser & CLI Argument Parsing — Teamocil's CLI uses Ruby's stdlib OptionParser (in lib/teamocil/cli.rb) to handle flags like --list, --edit, --here; understanding this pattern is useful for adding new global or layout-specific options.
• Pane Layout Algorithms (tmux layouts) — The layout: key in window definitions applies tmux's built-in layout algorithms (tiled, main-horizontal, etc.); understanding these informs how users structure complex multi-pane windows.

• tmuxinator/tmuxinator — Direct competitor in Ruby that also generates tmux sessions from YAML; more feature-rich (ERB templating, plugins) but heavier.
• jesseduffield/lazygit — TUI-based git client that uses tmux; represents a modern consumer of tmux automation in the ecosystem.
• tmux/tmux — Official tmux repository; Teamocil is a thin YAML wrapper around tmux's C codebase and control protocol.
• remiprev/teamocil-layouts — Community-contributed YAML layout examples for Teamocil; canonical reference for real-world usage patterns.
• gpakosz/.tmux — Popular tmux configuration framework; users often combine Teamocil (session setup) with this (window theming/bindings).

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for Command classes

The lib/teamocil/command/ directory contains 11 command classes (send_keys.rb, split_window.rb, etc.) but spec/teamocil/ lacks corresponding test files for these commands. Currently only cli_spec.rb and layout_spec.rb exist. Adding integration tests would ensure each command properly translates YAML configurations to tmux operations and catch regressions.

• [ ] Create spec/teamocil/command/ directory structure mirroring lib/teamocil/command/
• [ ] Add unit tests for each command class (send_keys_spec.rb, split_window_spec.rb, new_window_spec.rb, etc.)
• [ ] Test command execution with mock tmux sessions using the existing spec_helper.rb patterns
• [ ] Verify command output matches expected tmux behavior documented in README

Complete the truncated README.md options table and add configuration examples

The README.md shows an incomplete 'Global options' table that cuts off mid-definition. The installation instructions are present but lack concrete YAML layout examples referenced by '(look for sample layouts in this very README.md)'. Users cannot actually see the promised examples.

• [ ] Complete the Global options table in README.md with all available CLI options
• [ ] Add 3-5 concrete YAML layout examples (simple, intermediate, complex) showing windows, panes, splits, and send-keys
• [ ] Document the layout file structure and all supported YAML keys with examples
• [ ] Add troubleshooting section for common tmux/YAML errors

Add test coverage for error handling in Layout and invalid YAML scenarios

lib/teamocil/error/ contains InvalidYamlLayout and LayoutNotFound error classes, but spec/teamocil/layout_spec.rb doesn't appear to test error conditions comprehensively. Users need confidence that malformed YAML files produce helpful error messages.

• [ ] Expand spec/teamocil/layout_spec.rb with test cases for invalid YAML syntax
• [ ] Add tests for LayoutNotFound error when referencing missing layout files
• [ ] Add tests for InvalidYamlLayout with missing required fields (windows, panes, etc.)
• [ ] Verify error messages are user-friendly and guide troubleshooting (specific line numbers, expected format)

• Add tests for lib/teamocil/command/send_keys_to_pane.rb: Command file exists but has no corresponding spec file in spec/teamocil/command/; new contributor can write isolated unit tests mirroring send_keys_spec.rb pattern.
• Document YAML schema with examples in README.md: README shows sample layouts but lacks a formal schema reference table; contributor can extract and document all valid window/pane keys (name, root, layout, focus, options, panes) with type info.
• Add validation error message for missing name: in window definitions: README states name is required but current error handling in lib/teamocil/error/invalid_yaml_layout.rb may be generic; improve to give actionable feedback ('Window #1 is missing required key: name').

The Teamocil codebase has a moderate security posture. The primary concerns are around YAML deserialization vulnerabilities and command injection risks from user input handling. The tool's interaction with tmux through shell commands requires careful input validation. No critical vulnerabilities were identified, but medium-severity issues should be addressed, particularly around YAML parsing and sanitization of user-supplied data before shell execution. Dependency management practices should be verified (Gemfile.lock handling) and security scanning tools should be integrated into the CI/CD pipeline.

• Medium · Command Injection Risk in Tmux Integration — lib/teamocil/command/*.rb, lib/teamocil/tmux/*.rb. The codebase interacts with tmux through command execution (send_keys, split_window, etc.). If user-supplied YAML input is not properly sanitized before being passed to shell commands, it could lead to command injection attacks. Fix: Validate and sanitize all user input from YAML files before passing to tmux commands. Use parameterized/safe command execution methods instead of string interpolation for shell commands.
• Medium · YAML Deserialization Vulnerability — lib/teamocil/layout.rb. The application parses YAML files from user-defined layout directory (~/.teamocil/). Depending on how YAML is parsed, this could allow arbitrary code execution through YAML deserialization if using unsafe_load or equivalent. Fix: Use YAML.safe_load instead of YAML.load when parsing layout files. Ensure aliases and tags are restricted to safe types only.
• Low · Missing Input Validation on Layout Names — lib/teamocil/cli.rb, lib/teamocil/layout.rb. The CLI accepts layout names as arguments which are used to construct file paths. Without proper validation, this could potentially lead to directory traversal attacks (e.g., '../../etc/passwd'). Fix: Validate layout names to only allow alphanumeric characters, hyphens, and underscores. Reject any names containing path separators or dots.
• Low · No Dependency Lock File Visible — Gemfile, Gemfile.lock (missing). Gemfile is present but Gemfile.lock is not shown in the file structure. This could lead to inconsistent dependency versions across environments and potential use of vulnerable gem versions. Fix: Ensure Gemfile.lock is committed to version control. Regularly run 'bundle update' and use 'bundle audit' to check for known vulnerabilities in dependencies.
• Low · Potential Sensitive Data in Layout Files — ~/.teamocil/ (user directory). User layout files stored in ~/.teamocil/ may contain sensitive information (API keys, passwords, credentials). There's no encryption or access control mechanism mentioned. Fix: Document best practices for users about not storing sensitive data in layout files. Consider adding warnings in documentation and code comments.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.