FAQ

Why not just use Git for this?

Teams and repos are different things. Different people on the same project might use different teams. One developer uses a fullstack team while another uses a research team. You might also want the same team across multiple repos. Or agents on different platforms (for example, an OpenClaw research team alongside Claude Code developers) working in parallel on the same codebase.

Git cannot model any of this. It also means committing platform-specific config files ( .claude/agents/*.md , .cursor/agents/*.mdc , codex.md , etc.) into your repo. That pollutes version history with files that are not source code. teamrc generates them locally from a single definition and keeps them out of version control.

How does syncing work?

Your team's source of truth lives on the teamrc relay (a hosted server). When you run teamrc sync , the CLI compares content hashes to detect changes, pushes or pulls as needed, merges knowledge (append-only dedup), and regenerates platform config files. If both sides changed, the CLI pulls remote first and asks you to push manually. See the Syncing page for full details.

Do I need an account?

No. teamrc init and teamrc join work without any signup. Each machine gets an ed25519 keypair automatically. You can optionally link an account later for recovery and machine management via teamrc login .

What happens if two machines push conflicting changes?

Sync uses hash-based conflict detection. If only one side changed, it pushes or pulls automatically. If both sides changed and only knowledge differs, the CLI merges it (append-only dedup). If members or skills differ on both sides, the CLI pulls the remote version first and warns you to run teamrc push manually to override. To see what changed, use teamrc diff to compare your local state against the relay.

Knowledge always uses append-only deduplication, so knowledge from different machines is always combined, never overwritten.

Which platforms are supported?

Claude Code, Cursor, Codex, Gemini, and OpenClaw are fully supported. Each has an adapter that writes config in the platform's native format. The CLI auto-detects installed platforms and generates files for all of them. GitHub Copilot, Amazon Q, Windsurf, and Cline are planned. See the Platforms page for details on each.

Can I use teamrc across multiple projects?

Yes. A single team can be joined from multiple projects on the same machine or across different machines. Run teamrc join <invite-code> in each project directory. Each project gets its own generated config files but shares the same team definition. Changes sync across all of them.

Can different people on the same project use different teams?

Yes. Teams are per-machine, not per-repo. One developer might use a fullstack team with frontend and backend agents, while another uses a research team with specialized analysis agents. They work in the same codebase but with different AI configurations. Each person runs teamrc init or teamrc join independently.

Can I mix platforms on the same team?

Yes, that's the point. One machine might use Claude Code and Cursor, while another uses Gemini and OpenClaw. The team definition is the same. teamrc generates the right files for whatever platforms are detected on each machine. You can also restrict platforms per machine with the --platform flag or the platforms field in your YAML.

What's the difference between instructions and skills?

Instructions are unique to one agent. They define that agent's identity, personality, and specific directives. Skills are reusable blocks defined at the team level and assigned to one or more agents. Use instructions for "who this agent is" and skills for "what rules this agent follows." See Core Concepts for more.

Is my team config stored securely?

All requests to the relay are authenticated with ed25519 signatures. Only machines with valid tokens (from init or join ) can access your team's data. The relay stores your team configuration. It does not store source code or anything beyond what's in your .teamrc.yaml . See Authentication for details.

What's the difference between public and private teams?

Private teams (the default) are only visible to authenticated participants. If someone visits the team page URL without access, they see a "This team is private" message. Public teams can be viewed by anyone with the link. Visitors see a read-only view of member names, roles, instructions, and skill IDs/descriptions, and can clone it. Knowledge and skill bodies are redacted from public previews. They still cannot edit anything or see invites.

You can toggle visibility on the team dashboard at any time. Making a team public also generates a clone token that anyone can use to copy the config. See the Visibility section for more.

What's the difference between cloning and joining?

Cloning ( teamrc clone trc_cl_... ) copies the current team config locally. You get the YAML and generated files. Cloned teams support read-only pull ( teamrc pull ) to fetch updates from the original, but you cannot push changes or use sync. Clone tokens do not expire.

Joining ( teamrc join trc_inv_... ) creates an ongoing sync connection. Your machine becomes a participant and receives updates whenever the team changes. You can also push changes back. Invite codes expire after 24 hours.

Forking: to turn a cloned team into your own, run teamrc init in the same directory. It will adopt the existing definition, create a new team on the relay, and give you full ownership. The original team is not affected.

Use clone to try out someone's setup or as a starting point for your own team. Use join when you want to stay in sync with collaborators.

Can someone see my machine name?

No. Your machines are only visible to you, on your personal dashboard ( /dashboard ). Other participants cannot see your machine names, hostnames, or tokens. Machine names come from your computer's hostname and are only shared when you run teamrc login . The CLI warns you before sending it.

What if I lose my keypair?

Without a linked account, you need a new invite code from someone who still has access to the team. If you have linked an account (via teamrc login ), you can manage your machines from the web dashboard and recover access.

Can I edit .teamrc.yaml directly instead of using the web UI?

Yes. The YAML file is the source of truth. Edit it with any text editor, then run teamrc push to send changes to the relay and teamrc apply to regenerate local platform files. Or use teamrc sync to do both.

What does the daemon do?

teamrc daemon runs a background process that keeps the team knowledge file in sync across machines in real-time via WebSocket. It watches your local knowledge file for changes and pushes updates to the relay, and receives remote changes and merges them locally. The daemon syncs knowledge only. It does not sync team config (members, skills). Use teamrc sync for full team config sync.

How big can my team be?

When syncing through the relay, teams are currently limited to 20 members and 50 skills. The request payload is capped at 256 KB, knowledge at 100,000 bytes, and inline skill bodies at 10,000 bytes. Most teams have 3-8 members and 10-20 skills, so you're unlikely to hit these.

Can I use teamrc without the relay (offline only)?

Partially. You can write a .teamrc.yaml and run teamrc apply to generate platform files without ever connecting to the relay. But syncing, invites, and multi-machine support require the relay. You can also use teamrc clone to grab a one-time copy of a team without staying connected.