companies.sh

The CLI for the Agent Companies open standard.

Browse installable companies at companies.sh

Install a Company

npx companies.sh add paperclipai/companies/gstack

Source Formats

# GitHub shorthand (owner/repo/path)
npx companies.sh add paperclipai/companies/gstack

# GitHub tree URL
npx companies.sh add https://github.com/paperclipai/companies/tree/main/gstack

# Local path
npx companies.sh add ./my-company

Options

Examples

# Interactive import (prompts for source and target)
npx companies.sh add

# Import from a local folder with auto-bootstrap
npx companies.sh add ./fixtures/minimal-company

# Import into a new company
npx companies.sh add paperclipai/companies/gstack --target new

# Import into an existing company, pick from list
npx companies.sh add paperclipai/companies/gstack --target existing

# Import into a specific company without prompts
npx companies.sh add paperclipai/companies/gstack --target existing -C 

# Preview what would be imported
npx companies.sh add ./my-company --target existing -C  --dry-run

# Import specific agents only
npx companies.sh add paperclipai/companies/gstack --agents ceo,cto

# Import everything (agents, projects, tasks, skills)
npx companies.sh add paperclipai/companies/gstack --include company,agents,projects,tasks,skills

# Non-interactive usage for scripts or CI
npx companies.sh add paperclipai/companies/gstack --target new -y

# Use a specific Paperclip instance
npx companies.sh add paperclipai/companies/gstack --connection custom-url --api-base http://127.0.0.1:3100

Other Commands

# List all companies
npx companies.sh list

What is an Agent Company?

An Agent Company is a portable, markdown-first package that defines an AI-powered company — its agents, roles, projects, tasks, and skills — as plain files. Companies follow the Agent Companies open standard and can be imported into any supported orchestrator.

Companies let you:

• Spin up a fully staffed AI team from a single npx command
• Share and reuse organizational structures across projects
• Version-control your company configuration alongside your code

Package Layout

Creating a Company Package

Company packages are directories containing at least a COMPANY.md file with YAML frontmatter:

---
schema: agentcompanies/v1
name: My Company
slug: my-company
description: What this company does
---

# My Company

A description of the company and how it operates.

Add AGENTS.md, PROJECT.md, TASK.md, and SKILL.md files to define the rest of the organization. See the Agent Companies specification for the full schema.

How It Works

1. Resolve the source package from GitHub, a direct URL, or a local path.
2. Connect to the target orchestrator (Paperclip by default).
3. Prompt for the target company unless flags already provide it.
4. Normalize the requested include set and agent filters.
5. Execute the import through the orchestrator’s CLI.

companies.sh is a convenience wrapper — the chosen orchestrator performs the actual import.

Connection Modes

Paperclip Connection Flags

companies.sh requires paperclipai >= 2026.325.0. Fresh installs resolve a bundled release automatically.

Adding a Provider

companies.sh is provider-based. Paperclip is the first supported provider, but the architecture accepts additional agent orchestrators.

To add your orchestrator as a provider, open a pull request or issue with:

• The orchestrator name and a link to its documentation.
• A description of how it imports Agent Company packages.
• A CLI or SDK that companies.sh can shell out to for the import flow.

Telemetry

companies.sh sends one anonymous event after a successful import to help us understand package adoption. Telemetry is automatically disabled in CI environments.

• Uses a pseudonymous install id that rotates every 30 days.
• Does not send repo URLs, local paths, company names, or command arguments.
• Set DISABLE_TELEMETRY=1, DO_NOT_TRACK=1, or COMPANIES_TELEMETRY=0 to disable it.

The install id is stored at ~/.config/companies.sh/telemetry.json unless XDG_CONFIG_HOME overrides the base path.

Environment Variables

Troubleshooting

Import fails with collision errors

Use --collision skip to ignore conflicting entities, or --collision replace to overwrite them.

Dry-run shows nothing to import

Confirm the source contains valid Agent Company files (COMPANY.md, AGENTS.md) at the expected paths.

Use a different paperclipai build

export PAPERCLIPAI_CMD=/path/to/paperclipai

# With prefix arguments
export PAPERCLIPAI_CMD="pnpm --dir /path/to/paperclip paperclipai"

Local auto-bootstrap times out

Raise the timeout for slow machines or Docker:

export COMPANIES_PAPERCLIP_START_TIMEOUT_MS=180000

Related Links

• Agent Companies Specification
• Browse Companies
• Paperclip
• Paperclip Documentation

Contributing

See DEVELOPING.md for build instructions, testing workflows, and maintainer notes.

License

MIT