FAQ

General

What is cliq?

cliq is a multi-agent orchestration framework. It coordinates multiple AI agents — each with a defined role, domain, and boundaries — into workflows that produce structured, reviewed output. Teams are portable directories you can build, share, and run from three commands. The infrastructure is domain-agnostic: engineering, product, content, compliance, research — any workflow where specialist agents need to collaborate.

How is cliq different from LangChain, CrewAI, and AutoGen?

Those are frameworks for building agent systems. cliq is a ready-made agent system you configure and run. They sell lumber. cliq sells houses.

	LangChain / LangGraph	CrewAI	AutoGen	cliq
What you get	Toolkit	Library	Research framework	Ready-made teams
To use it	Write Python	Write Python	Write Python	Run a command
Shareable units	—	—	—	Portable team packages
Time to first value	Hours / days	Hours	Hours	Minutes
Workflow model	Code-defined graphs	Sequential / hierarchical	Conversations	DAG with gates
Debugging	Python stack traces	Python stack traces	Python stack traces	Read files on disk

If you want to build a custom agent framework, use a framework. If you want a team of agents that delivers production-quality work from a single command, use cliq.

How is cliq different from using a single AI agent?

Single Agent	cliq
One context window	Multiple specialized agents with focused roles
You review everything	Automated gate reviews with commands and iteration
No structure	Workflows enforce phase order, dependencies, and handoffs
No feedback loop	Gates route work back for remediation automatically
Sequential prompting	Parallel execution in tmux
Ad-hoc every time	Reusable teams you deploy in one command

Is cliq open source?

Yes. MIT licensed. No vendor lock-in, no usage limits, no surprise pricing.

What AI models does cliq support?

cliq supports multiple built-in agents: Cursor, Claude Code, Gemini CLI, and Codex. Each agent wraps its CLI tool using the Cliq SDK. cliq is model-agnostic — it orchestrates agents, it doesn’t provide the AI. You can also build custom agents powered by any LLM API.

Does cliq require a server?

No. cliq uses a filesystem-based coordination protocol. Agents communicate through channels (directories) for handoffs and signals (files) for coordination. No server, no shared memory, no database needed for running pipelines.

The optional cliq server provides an HTTP/WebSocket API, web Dashboard, and A2A agent mode for programmatic control — but it’s not required.

Setup & Requirements

What do I need to install?

Requirement	Notes
Node.js	18 or higher
Agent	At least one: Cursor CLI, Claude Code, Gemini CLI, or Codex
tmux	Terminal multiplexer — `brew install tmux` on macOS
git	Required for teams that manage branches and PRs

Run cliq doctor to verify your environment.

What operating systems are supported?

macOS and Linux. Windows via WSL2 is community-tested but not officially supported.

What is `cliq doctor`?

A diagnostic command that checks your environment: Node.js version, agent binary availability, tmux installation, settings validity, integration connectivity, and HUG server reachability (if configured). Run it whenever something isn’t working.

Where does cliq store its data?

~/.cliqrc/ is the home directory. It contains:

settings.json — global configuration
teams/ — team registry organized by scope (@local/, @cliq/, etc.)
cliq.db — SQLite database for instance tracking and server state
id — your unique cliq identity

Each project gets a .cliq/ directory (created by cliq init) containing deployed roles, channels, signals, prompts, and orchestration artifacts.

Teams

What is a team?

A team is a directory containing a team.yml (workflow definition) and a roles/ folder (one markdown file per agent). Teams are portable — copy the directory and it works anywhere cliq is installed.

Where do teams come from?

Three sources:

CliqHub / @cliq scope — official curated teams. Install via cliq team install hub://.
@local scope — teams you create yourself with cliq team create or cliq builder generate, or copied with cliq team copy and installed via cliq team install.
Custom scopes — team repos from colleagues or your organization, installed via cliq team install.

How do I see what teams I have?

cliq team list

Shows all installed teams across all scopes.

How do I inspect a team before running it?

cliq team info @cliq/hello-world

Shows the workflow phases, dependencies, roles, commands, and A2A metadata.

What does `@local` mean?

@local is the reserved scope for teams on your machine. Any team you create lands here (~/.cliqrc/teams/@local/<name>/). It cannot be published to CliqHub.

What happens if two scopes have a team with the same name?

If you use a bare name (e.g. cliq assemble feature-dev-js) and it exists in multiple scopes, cliq raises an error and asks you to specify the full @scope/name. No silent priority — ambiguity is always an error.

Can I edit a team after installing it?

Yes. Teams are just directories on disk. Edit team.yml or any file in roles/ directly. To preserve changes across future installs, copy the team first and install it under @local: cliq team copy @cliq/hello-world ./my-hello-world then cliq team install ./my-hello-world.

Running Pipelines

What are the basic commands?

cliq init                              # create .cliq/ in your project
cliq assemble @cliq/hello-world        # deploy the team
cliq req -m "your requirement"         # set the requirement
cliq run                               # launch the pipeline

What does `cliq assemble` do?

It copies the team’s workflow and role files into your project’s .cliq/ directory. After assembly, the project is self-contained — it doesn’t need the registry at runtime.

What does `cliq req` do?

It resolves your requirement into a task specification, generates activation prompts for each agent, and creates the channel structure for handoffs between phases.

Can I re-run a pipeline?

Yes. Run cliq run again (or cliq run -f to skip confirmation). You don’t need to re-run cliq req — the requirement hasn’t changed. Only re-run cliq req if you want to change the requirement.

How do I cancel a running pipeline?

Press Ctrl+C in the tmux session, or from another terminal: cliq run --cancel. If using the server API: POST /jobs/cancel/.

What is tmux and why does cliq use it?

tmux is a terminal multiplexer. cliq uses it to run multiple agents simultaneously — each agent gets its own tmux pane. Use Ctrl+B then arrow keys to switch between panes and watch agents work in real time.

Can I run pipelines headlessly?

Yes. Use cliq run --headless to run without tmux — useful for CI/CD or scripted environments. The orchestrator runs in the foreground and logs to stdout.

How long does a pipeline take?

Depends on complexity and team size. Simple teams (3-4 agents) typically complete in 1-3 minutes. Larger teams with gates and iteration cycles may take 3-8 minutes. Parallel execution keeps total time low even with many agents.

Workflows & Phases

What are the phase types?

Type	Purpose
standard	An agent does work (research, write, implement, etc.)
gate	Runs automated commands, then an agent evaluates and renders a verdict (PASS / ROUTE / ESCALATE)
exec	Runs shell commands only — no agent, no iteration. Pass or escalate based on `escalate_on_fail`.
pull	Fetches external content into `.cliq/pull/` — no agent.
push	Publishes local files to external destinations — no agent.

Support phases are declared in a separate support: section under workflow and sit outside the main DAG. They’re only activated when a gate routes work to them.

See Workflows & Phases for the full reference.

What is a gate?

A gate is a quality checkpoint. It runs deterministic shell commands (commands), then launches an agent to evaluate the result. The gate agent can PASS the pipeline forward, ROUTE work to a support phase for fixes, or ESCALATE to a human. Gates can iterate — if routed work comes back, the gate re-evaluates, up to max_iterations.

What happens when a gate exhausts its iterations?

It auto-escalates. The pipeline halts and asks for human intervention. Fix the issue and run cliq run to resume.

Can phases run in parallel?

Yes. Phases with no dependency relationship run simultaneously. The orchestrator resolves the DAG and launches independent phases in parallel. Use depends_on to control ordering — a phase waits for all its dependencies before starting.

What are commands?

Shell commands attached to gate, hug, or exec phases. Exit code 0 = pass, non-zero = fail. Examples: test -f output.md, npm test, grep -q '## Introduction' article.md. They run before the gate agent evaluates, giving the agent objective data to reason about.

Roles

What is a role?

A markdown file that gives an agent its identity, responsibilities, boundaries, and workflow instructions. It’s the single most important lever you have over agent behavior. A specific, well-structured role produces focused work. A vague role produces wandering output.

Where do roles live?

In the team package: ~/.cliqrc/teams/@scope/team-name/roles/<phase>.md. After assembly, deployed copies live in your project at .cliq/roles/<phase>.md.

Can I edit roles without rebuilding?

Yes. For quick iteration, edit .cliq/roles/<phase>.md directly in your project and re-run with cliq run -f. For permanent changes, edit the source in the team package and re-assemble.

What makes a good role?

Name exact file paths for reads and writes
Set hard boundaries (DO / DO NOT / MAY)
Include a quality checklist at the end
Handle re-engagement (tell the agent to read .cliq/gate_context.md if it’s a gate or fixer role)
Be specific — “Write findings to .cliq/design/research.md” beats “write your findings”

See Roles and Build from Scratch — Roles for detailed guidance.

Human Gate (HUG)

What is a Human Gate?

A hug phase where a human reviewer — not an AI agent — renders the verdict. The pipeline pauses, sends notifications to reviewers, and presents a web-based review page. The reviewer can approve, reject, or request changes. See HUG Overview.

Do I need a separate server for HUG?

Yes. The HUG server (@cliq/hug-server npm package or Docker image) runs separately from cliq. It stores reviews in PostgreSQL, serves the review page, and handles the chat assistant. See HUG Server.

How do reviewers get notified?

Via channels configured in settings.json — Slack webhooks, custom webhook URLs, or any URL-based notification target. Notifications include a link to the review page.

Can reviewers chat with an AI assistant on the review page?

Yes, if hug.enable_chat is true and hug.llm.provider is configured. The assistant has context about the pipeline, the requirement, the artifacts under review, and the review history. It can answer questions like “what changed since the last review?” See Configuring a HUG.

What happens when a reviewer requests changes?

The pipeline routes work back to the target phase specified in the workflow’s route_targets. The routed phase receives the reviewer’s feedback as input and can address it. The pipeline then returns to the HUG for re-evaluation.

How long do review links stay active?

Pending reviews expire after the configured timeout (default: 24 hours). Completed reviews are retained for 30 days (configurable via REVIEW_RETENTION_DAYS on the HUG server) so multiple reviewers can reference past decisions.

Builder

What is the Builder?

An AI-powered tool that generates complete teams from natural language descriptions. It produces the team.yml, all role files, gate commands, and A2A metadata fields (tags, inputs, use_when, not_for).

cliq builder generate -m "Content pipeline with researcher, writer, editor, and quality gate"

Can I refine a generated team?

Yes. Use cliq builder improve <team> --role <role> --instruction "..." to refine individual roles, and cliq builder gaps <team> to find structural holes. See Generate with Builder.

Does the Builder require an API key?

Yes. Configure a provider (OpenAI, Anthropic, or Google) in ~/.cliqrc/settings.json under the builder section. See Builder Reference.

Configuration

Where are settings stored?

Two levels:

Global: ~/.cliqrc/settings.json — applies to all projects
Project: .cliq/settings.json — overrides for a specific project (created by cliq assemble if the team provides one)

Project settings are deep-merged on top of global settings at runtime.

What goes in settings?

Agent configuration, integration credentials (GitHub, Slack, Jira), HUG server URL and reviewer definitions, notification channels, builder provider, A2A configuration, and logging levels. See Settings for the full reference.

How do I use teams from a shared directory?

Install them with cliq team install <path>:

cliq team install ~/org-teams/@myorg/deploy-pipeline

This copies the team into ~/.cliqrc/teams/ and records its source for future updates.

How do I validate my configuration?

cliq doctor

Checks settings structure, integration connectivity, HUG server reachability, agent binary availability, and more.

Integrations

What integrations are supported?

Integration	What it does
GitHub	PR creation, reviewer assignment, label management
Bitbucket Cloud	PR creation and verification
Jira	Fetch ticket requirements, post comments, transition tickets
Slack	Pipeline and HUG review notifications

Can I use cliq with existing projects?

Yes. Run cliq init in any project directory, assemble a team, set a requirement, and run. cliq reads your existing codebase as context.

Can cliq work across multiple repositories?

Yes. Clone repos into a workspace directory and initialize cliq — it auto-detects child git repos. Each repo gets its own branch and PR.

What is pull and push?

Pull and push are dedicated phase types for external file operations. A type: pull phase fetches external content (Google Drive, URLs, PDFs) into .cliq/pull/. A type: push phase delivers local files to external systems (Google Drive, Google Docs). Both participate in the DAG like any other phase. See Pull & Push.

A2A & Server

What is the cliq server?

A local HTTP + WebSocket server (cliq server start) that exposes the cliq engine via an API. It enables programmatic pipeline control, real-time event streaming, and serves the web Dashboard. See Cliq Server.

What is A2A?

Agent-to-Agent protocol support. When cliq server start --a2a is used, other AI systems can discover cliq’s capabilities and invoke pipelines via standard A2A messages. cliq becomes a callable capability in a larger agent ecosystem. See A2A Agent Mode.

What is a mesh?

A network of A2A agents that can discover and invoke each other. cliq can register with mesh networks (currently Savant) so routers can automatically dispatch tasks to the right cliq team based on capability matching.

Do I need the server to run pipelines?

No. cliq run works standalone. The server is for programmatic control, monitoring, and A2A integration.

Security & Privacy

Where does my code go?

Nowhere beyond your machine. cliq runs entirely locally. Your code never leaves your environment. AI model calls go through your configured agent — cliq itself doesn’t make model API calls (except for Builder and HUG chat, which use explicitly configured provider keys).

Are my API tokens safe?

Settings files (~/.cliqrc/settings.json and .cliq/settings.json) are gitignored by default. The cliq status -v command masks sensitive values. Tokens are only read at runtime from the local filesystem.

Can I control how far git automation goes?

Yes. The finalize_to setting controls the automation boundary:

Value	What happens
`commit`	Stage and commit only. You push and create the PR.
`push`	Commit and push. You create the PR.
`pr`	Commit, push, and create PR. You review and merge. (default)

A human always merges. cliq never pushes to your main branch directly.

Troubleshooting

What if the pipeline fails?

Check .cliq/orchestrator.log for the execution timeline
Check .cliq/reviews/ for gate review findings
Check .cliq/signals/ for verdict details
Fix the issue
Run cliq run again (or cliq run -f to skip confirmation)

You don’t need to re-run cliq req — the requirement hasn’t changed.

What if a gate keeps failing?

Gates have an iteration budget (max_iterations, default: 3). If the gate can’t pass within budget, it escalates. Review the gate’s command results and review findings. Common fixes:

Fix the underlying issue and re-run
Adjust max_iterations in the workflow
Add if conditions to skip commands that don’t apply
Review the gate role — is it giving clear, actionable feedback when routing?

How do I debug agent behavior?

Everything is on disk:

Directory	What’s there
`.cliq/prompts/`	Activation prompts — exactly what each agent received
`.cliq/channels/`	Handoff artifacts between agents
`.cliq/signals/`	Completion signals and gate verdicts
`.cliq/reviews/`	Gate review findings
`.cliq/gate_context.md`	Command results and verdict history for the current gate cycle
`.cliq/orchestrator.log`	Full pipeline execution log

`cliq doctor` says something is wrong — what do I do?

The doctor output tells you exactly what failed and usually suggests a fix. Common issues:

Missing agent binary: Install at least one agent CLI (Cursor, Claude Code, Gemini CLI, or Codex)
tmux not found: brew install tmux (macOS) or apt install tmux (Linux)
HUG server unreachable: Check hug.server_url in settings and verify the server is running
Invalid settings: Check for typos in ~/.cliqrc/settings.json — the doctor catches unrecognized keys

Can I run cliq in Docker?

Yes. Use docker.enabled: true in settings or pass --docker to cliq run. Each pipeline runs in an isolated container. See Docker Isolation.

Can I run cliq on Kubernetes?

Yes. Set kubernetes.enabled: true and deploy with the Helm chart. Pipelines run as K8s Jobs with shared PVC storage (requires PostgreSQL). See Kubernetes Deployment.

Do I need PostgreSQL?

Only for multi-replica server deployments (Kubernetes) or the HUG server. For everything else, SQLite is the default and works fine.

Where do I get help?

GitHub Issues — bug reports and feature requests
GitHub Discussions — questions and community help

FAQ