@quiel/cli 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +137 -0
- package/README.ru.md +137 -0
- package/dist/cli.js +1112 -439
- package/package.json +15 -3
package/README.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# @quiel/cli
|
|
2
|
+
|
|
3
|
+
**Русская версия — [README.ru.md](https://github.com/Quiel-AI/quiel-cli/blob/main/README.ru.md).**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@quiel/cli)
|
|
6
|
+
|
|
7
|
+
The Quiel client: a CLI **and** an MCP server that connects your coding agent — Claude Code, Codex, Cursor or OpenCode — to a project on a [Quiel](https://quiel.ai) platform.
|
|
8
|
+
|
|
9
|
+
Quiel is a hosted product that orchestrates a team and the coding agents its members run: tasks live in one graph, each person connects their own agent, and in autonomous mode the agent picks up tasks for its role, does the work, pushes to git and reports back — while people watch it happen and stay in the loop.
|
|
10
|
+
|
|
11
|
+
This package is the part that runs **on your machine**.
|
|
12
|
+
|
|
13
|
+
## What it does
|
|
14
|
+
|
|
15
|
+
- **Gives your agent the platform's tools over MCP** — take the next task, read project context and documents, ask a human, request approval for a dangerous action, submit work.
|
|
16
|
+
- **Installs hooks into your agent** so a shell command is checked against the project's trust profile *before* it runs. A command that matches a stop pattern is refused; a command that needs a human gets one.
|
|
17
|
+
- **Keeps the connection and the task lease alive**, so the platform knows the task is being worked on and not abandoned.
|
|
18
|
+
|
|
19
|
+
It never sends the contents of your files anywhere — only file names, paths and commands.
|
|
20
|
+
|
|
21
|
+
## Requirements
|
|
22
|
+
|
|
23
|
+
- Node.js 22 or newer
|
|
24
|
+
- An account on a Quiel platform, membership in a project, and at least one role there
|
|
25
|
+
- An agent token — issued once, on the project's **Agents** page
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm i -g @quiel/cli
|
|
31
|
+
quiel --version
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
Run this in your project directory:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
quiel init
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
It asks which agent you use (offering the one it found in the directory first), the platform address, your token, the project key, the agent id and its roles. If you already know the agent, skip the question:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
quiel init --agent codex
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Then **restart your agent's session** — this is required, not a suggestion: the MCP server only starts when a session starts. Without a restart the agent will not show up, no matter how many times you run `init`.
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
quiel status --check # connection, mode, current task
|
|
52
|
+
quiel connect # hold the connection to the platform
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
To let the agent pick up tasks by itself:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
quiel mode auto
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Supported agents
|
|
62
|
+
|
|
63
|
+
| Agent | Maker | `--agent` | State |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Claude Code | Anthropic | `claude-code` | Verified by a live run |
|
|
66
|
+
| Codex | OpenAI | `codex` | Beta |
|
|
67
|
+
| Cursor | Anysphere | `cursor` | Beta |
|
|
68
|
+
| OpenCode | SST | `opencode` | Beta |
|
|
69
|
+
|
|
70
|
+
One client covers all of them. The platform's tools are MCP — an industry standard — and behave the same everywhere; only the hook format and the configuration files differ, and the client writes the right ones for the agent you picked.
|
|
71
|
+
|
|
72
|
+
### What "beta" means here
|
|
73
|
+
|
|
74
|
+
Support for Codex, Cursor and OpenCode is built from each platform's official documentation and covered by tests, but it has **not been verified by a live run yet**. In practice: the tools will show up, but check the protection yourself — ask the agent to run a command you know is forbidden and make sure it does not go through. Do not assume stop patterns are protecting you until you have seen a refusal with your own eyes.
|
|
75
|
+
|
|
76
|
+
`quiel init` and `quiel status` both say so out loud for these agents.
|
|
77
|
+
|
|
78
|
+
Two gaps worth knowing about, and neither is an omission on our side — the platform simply does not report the event, so there is nothing to intercept:
|
|
79
|
+
|
|
80
|
+
| | Claude Code | Codex | Cursor | OpenCode |
|
|
81
|
+
|---|---|---|---|---|
|
|
82
|
+
| Platform tools (MCP) | yes | yes | yes | yes |
|
|
83
|
+
| Blocking dangerous commands | yes | yes | yes | yes |
|
|
84
|
+
| Path-based file protection | yes | yes | **no** | yes |
|
|
85
|
+
| Autonomous mode | yes | yes | yes | yes |
|
|
86
|
+
| Moving to "rate limited" on its own | yes | **no** | **no** | yes |
|
|
87
|
+
|
|
88
|
+
**OpenCode, specifically:** it had a bug where tool calls *from a subagent* did not trigger plugins at all ([sst/opencode#5894](https://github.com/anomalyco/opencode/issues/5894) — closed, but the fixed version is not named). Quiel's own instructions tell the agent to delegate work to a subagent, so test the refusal through a subagent.
|
|
89
|
+
|
|
90
|
+
## What `quiel init` writes
|
|
91
|
+
|
|
92
|
+
Everything goes into your project directory, so it is visible in `git status` and reviewable:
|
|
93
|
+
|
|
94
|
+
| Agent | Files |
|
|
95
|
+
|---|---|
|
|
96
|
+
| Claude Code | `.claude/settings.json`, `.mcp.json`, a section in `CLAUDE.md`, `.claude/commands/quiel-auto.md` |
|
|
97
|
+
| Codex | `.codex/hooks.json`, `.codex/config.toml`, a section in `AGENTS.md` |
|
|
98
|
+
| Cursor | `.cursor/hooks.json`, `.cursor/mcp.json`, a section in `AGENTS.md` |
|
|
99
|
+
| OpenCode | `opencode.json`, `.opencode/plugins/quiel.js`, a section in `AGENTS.md` |
|
|
100
|
+
|
|
101
|
+
Plus one line in `.gitignore` for the directory the agent works in.
|
|
102
|
+
|
|
103
|
+
**Your token goes into none of them.** It is stored separately in `~/.quiel/credentials.json` with `0600` permissions, outside the repository. `.quiel.json` — the file that *is* committed — holds only the platform address, the project key, the agent id, its roles and which agent program you chose.
|
|
104
|
+
|
|
105
|
+
Existing configuration is merged, not overwritten: other MCP servers, other hooks and your own comments survive. Running `init` again is the normal way to reconnect an agent, and it does not duplicate anything.
|
|
106
|
+
|
|
107
|
+
## Commands
|
|
108
|
+
|
|
109
|
+
| Command | What it does |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `quiel init` | Connect this project: write `.quiel.json`, the agent's configuration and the instructions section |
|
|
112
|
+
| `quiel connect` | Hold the connection to the platform |
|
|
113
|
+
| `quiel status [--check]` | Show the project, the configured agent program, mode and current task |
|
|
114
|
+
| `quiel mode auto\|manual` | Switch between autonomous and manual |
|
|
115
|
+
| `quiel mcp` | Run the MCP server over stdio (your agent starts this itself) |
|
|
116
|
+
| `quiel hook <name> [--format …]` | Run a hook (your agent's configuration calls this) |
|
|
117
|
+
|
|
118
|
+
## Reporting a problem
|
|
119
|
+
|
|
120
|
+
Issues are open: **https://github.com/Quiel-AI/quiel-cli/issues**
|
|
121
|
+
|
|
122
|
+
Please include the output of:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
quiel --version
|
|
126
|
+
quiel status
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`quiel status` does **not** print your token. It does print your platform address, project key and agent id — redact them if that matters to you.
|
|
130
|
+
|
|
131
|
+
## About this repository
|
|
132
|
+
|
|
133
|
+
This repository is the documentation and the issue tracker for `@quiel/cli`. Quiel is a commercial hosted product: the client is distributed as a built package under a proprietary licence, and its source is not published here. What the client does to your machine is documented above — and every file it writes lands in your project directory, where you can read it.
|
|
134
|
+
|
|
135
|
+
## Licence
|
|
136
|
+
|
|
137
|
+
Proprietary (`UNLICENSED`). Copyright © Quiel. All rights reserved.
|
package/README.ru.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# @quiel/cli
|
|
2
|
+
|
|
3
|
+
**English version — [README.md](https://github.com/Quiel-AI/quiel-cli/blob/main/README.md).**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@quiel/cli)
|
|
6
|
+
|
|
7
|
+
Клиент Quiel: одновременно CLI **и** MCP-сервер, который подключает вашу агентскую программу — Claude Code, Codex, Cursor или OpenCode — к проекту на платформе [Quiel](https://quiel.ai).
|
|
8
|
+
|
|
9
|
+
Quiel — это продукт, который оркеструет команду и агентов её участников: задачи хранятся в едином графе, каждый подключает своего агента, и в автономном режиме агент сам забирает задачи своей роли, выполняет их, пушит в git и отчитывается — а люди всё это время видят происходящее и остаются в контуре.
|
|
10
|
+
|
|
11
|
+
Этот пакет — та часть, что работает **на вашей машине**.
|
|
12
|
+
|
|
13
|
+
## Что он делает
|
|
14
|
+
|
|
15
|
+
- **Даёт вашему агенту инструменты платформы по MCP** — взять следующую задачу, прочитать контекст и документы проекта, задать вопрос человеку, попросить подтверждение на опасное действие, сдать работу.
|
|
16
|
+
- **Ставит хуки в вашего агента**, чтобы shell-команда проверялась по профилю доверия проекта *до* выполнения. Команда из стоп-списка получает отказ; команда, требующая человека, — вопрос человеку.
|
|
17
|
+
- **Держит соединение и аренду задачи**, чтобы платформа знала: над задачей работают, а не бросили её.
|
|
18
|
+
|
|
19
|
+
Содержимое ваших файлов никуда не отправляется — только имена, пути и команды.
|
|
20
|
+
|
|
21
|
+
## Что нужно
|
|
22
|
+
|
|
23
|
+
- Node.js 22 или новее
|
|
24
|
+
- Учётная запись на платформе Quiel, участие в проекте и хотя бы одна роль в нём
|
|
25
|
+
- Токен агента — выдаётся один раз, на странице «Агенты» проекта
|
|
26
|
+
|
|
27
|
+
## Установка
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm i -g @quiel/cli
|
|
31
|
+
quiel --version
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Быстрый старт
|
|
35
|
+
|
|
36
|
+
Выполните в каталоге своего проекта:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
quiel init
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Команда спросит, какой у вас агент (найденный в каталоге предложит первым), адрес платформы, токен, ключ проекта, ID агента и роли. Если агент известен заранее — можно без вопроса:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
quiel init --agent codex
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Затем **перезапустите сессию своей программы**. Это обязательный шаг, а не совет: MCP-сервер поднимается только при старте сессии. Без перезапуска агент не появится, сколько бы раз вы ни выполняли `init`.
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
quiel status --check # соединение, режим, текущая задача
|
|
52
|
+
quiel connect # держит соединение с платформой
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Чтобы агент начал брать задачи сам:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
quiel mode auto
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Какие агенты поддерживаются
|
|
62
|
+
|
|
63
|
+
| Агент | Кто делает | `--agent` | Состояние |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Claude Code | Anthropic | `claude-code` | Проверено живым прогоном |
|
|
66
|
+
| Codex | OpenAI | `codex` | Бета |
|
|
67
|
+
| Cursor | Anysphere | `cursor` | Бета |
|
|
68
|
+
| OpenCode | SST | `opencode` | Бета |
|
|
69
|
+
|
|
70
|
+
Клиент один на всех. Инструменты платформы — это MCP, отраслевой стандарт, и они работают одинаково везде; различаются только формат хуков и файлы конфигурации, и клиент пишет те, что нужны выбранному агенту.
|
|
71
|
+
|
|
72
|
+
### Что означает «бета»
|
|
73
|
+
|
|
74
|
+
Поддержка Codex, Cursor и OpenCode сделана по официальной документации каждой платформы и покрыта тестами, но **живым прогоном пока не проверена**. На практике это значит: инструменты появятся, а защиту проверьте сами — попросите агента выполнить заведомо запрещённую команду и убедитесь, что она не прошла. Не считайте, что стоп-паттерны вас защищают, пока не увидели отказ своими глазами.
|
|
75
|
+
|
|
76
|
+
`quiel init` и `quiel status` говорят об этом вслух для таких агентов.
|
|
77
|
+
|
|
78
|
+
Два пробела, о которых стоит знать. Ни один из них не наша недоделка: платформа просто не сообщает о таком событии, и перехватывать нечего.
|
|
79
|
+
|
|
80
|
+
| | Claude Code | Codex | Cursor | OpenCode |
|
|
81
|
+
|---|---|---|---|---|
|
|
82
|
+
| Инструменты платформы (MCP) | да | да | да | да |
|
|
83
|
+
| Запрет опасных команд | да | да | да | да |
|
|
84
|
+
| Защита файлов по путям | да | да | **нет** | да |
|
|
85
|
+
| Автономный режим | да | да | да | да |
|
|
86
|
+
| Переход в «Лимит запросов» сам | да | **нет** | **нет** | да |
|
|
87
|
+
|
|
88
|
+
**Отдельно про OpenCode:** у него была ошибка, из-за которой вызовы инструментов *из субагента* не поднимали плагины вовсе ([sst/opencode#5894](https://github.com/anomalyco/opencode/issues/5894) — закрыт, но версия с исправлением не названа). Инструкция Quiel как раз велит агенту делегировать работу субагенту — проверьте отказ именно через субагента.
|
|
89
|
+
|
|
90
|
+
## Что записывает `quiel init`
|
|
91
|
+
|
|
92
|
+
Всё ложится в каталог проекта, поэтому видно в `git status` и доступно для просмотра:
|
|
93
|
+
|
|
94
|
+
| Агент | Файлы |
|
|
95
|
+
|---|---|
|
|
96
|
+
| Claude Code | `.claude/settings.json`, `.mcp.json`, секция в `CLAUDE.md`, `.claude/commands/quiel-auto.md` |
|
|
97
|
+
| Codex | `.codex/hooks.json`, `.codex/config.toml`, секция в `AGENTS.md` |
|
|
98
|
+
| Cursor | `.cursor/hooks.json`, `.cursor/mcp.json`, секция в `AGENTS.md` |
|
|
99
|
+
| OpenCode | `opencode.json`, `.opencode/plugins/quiel.js`, секция в `AGENTS.md` |
|
|
100
|
+
|
|
101
|
+
Плюс одна строка в `.gitignore` — для каталога, в котором работает агент.
|
|
102
|
+
|
|
103
|
+
**Токен не попадает ни в один из них.** Он лежит отдельно, в `~/.quiel/credentials.json` с правами `0600`, вне репозитория. В `.quiel.json` — том файле, который коммитится, — только адрес платформы, ключ проекта, ID агента, его роли и выбранная агентская программа.
|
|
104
|
+
|
|
105
|
+
Существующая конфигурация сливается, а не перезаписывается: чужие MCP-серверы, чужие хуки и ваши комментарии сохраняются. Повторный `init` — это штатный способ переподключить агента, и он ничего не дублирует.
|
|
106
|
+
|
|
107
|
+
## Команды
|
|
108
|
+
|
|
109
|
+
| Команда | Что делает |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `quiel init` | Подключить проект: `.quiel.json`, конфигурация агента, секция в инструкциях |
|
|
112
|
+
| `quiel connect` | Держит соединение с платформой |
|
|
113
|
+
| `quiel status [--check]` | Показывает проект, настроенную программу, режим и текущую задачу |
|
|
114
|
+
| `quiel mode auto\|manual` | Переключает автономный и ручной режим |
|
|
115
|
+
| `quiel mcp` | Запускает MCP-сервер по stdio (это делает сам агент) |
|
|
116
|
+
| `quiel hook <name> [--format …]` | Вызывает хук (это делает конфигурация агента) |
|
|
117
|
+
|
|
118
|
+
## Сообщить о проблеме
|
|
119
|
+
|
|
120
|
+
Issues открыты: **https://github.com/Quiel-AI/quiel-cli/issues**
|
|
121
|
+
|
|
122
|
+
Приложите, пожалуйста, вывод:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
quiel --version
|
|
126
|
+
quiel status
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`quiel status` **не** печатает ваш токен. Но он печатает адрес платформы, ключ проекта и ID агента — замажьте их, если это важно.
|
|
130
|
+
|
|
131
|
+
## Об этом репозитории
|
|
132
|
+
|
|
133
|
+
Здесь — документация и трекер задач для `@quiel/cli`. Quiel — коммерческий продукт: клиент распространяется собранным пакетом под закрытой лицензией, исходники здесь не публикуются. Что клиент делает с вашей машиной, описано выше, и каждый файл, который он пишет, лежит в вашем же каталоге проекта — его можно прочитать.
|
|
134
|
+
|
|
135
|
+
## Лицензия
|
|
136
|
+
|
|
137
|
+
Закрытая (`UNLICENSED`). © Quiel. Все права защищены.
|