vibecoderscrew

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #go #rust #deep-learning #macos #awesome #cli #vue #pytorch #ios

(★ 9)

VibecodersCrew — local AI agent workspace with OpenAI Codex support. Independent community product based on Kiro Crew (Apache-2.0). Not affiliated with Amazon or OpenAI.

vibecoderscrew Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">VibecodersCrew</h1>

Local AI agent workspace. Persistent sessions, skills, schedules,
 and a dashboard: on hardware you control.

<a href="#download">Source release</a> ·
 <a href="#run-from-source">Run from source</a> ·
 <a href="#requirements">Requirements</a> ·
 <a href="#desktop-app">Desktop app</a> ·
 <a href="#what-it-does">What it does</a> ·
 <a href="#docs">Docs</a>

## Download

The v1.0.1 candidate is a source-only release. The GitHub release page provides
the repository source archive and release notes; desktop installers and update
feeds are outside this fork's distribution boundary.

Use the source archive from the [v1.0.1 release page](https://github.com/serejaris/vibecoderscrew/releases/tag/v1.0.1),
or clone the repository and follow [Run from source](#run-from-source) below.

## Run from source

### Requirements

- macOS or Linux (Windows: [docs/windows-install.md](docs/windows-install.md))
- Python 3.10–3.13
- Node.js 18+ and npm
- A working [Codex](https://github.com/openai/codex) login (CLI or ChatGPT desktop app on macOS)

### 1. Clone and build

```bash
git clone https://github.com/serejaris/vibecoderscrew.git
cd vibecoderscrew
make build
source .venv/bin/activate
```

`make build` builds the web dashboard and installs the Python package into `.venv`.

### 2. Point the agent at Codex

```bash
vibecoderscrew config set agent.provider codex
vibecoderscrew config set agent.model auto
vibecoderscrew doctor
```

`doctor` checks that Codex is on the path / discoverable and that you are logged in.

### 3. Start the gateway

```bash
vibecoderscrew gateway
```

Open the dashboard URL printed in the terminal (default `http://127.0.0.1:5476`).

Useful commands after install:

```bash
vibecoderscrew --version
vibecoderscrew setup          # optional wizard
vibecoderscrew doctor         # health check
vibecoderscrew gateway        # API + dashboard
vibecoderscrew chat           # CLI chat against the same gateway
```

The package also installs a `kirocrew` command as a compatibility alias of `vibecoderscrew`.

### Desktop app

For local development only, you can build a desktop app with the backend bundled
(no system Python needed at runtime):

```bash
UNIVERSAL=0 make desktop
```

The local build lands under `website/electron/dist/`; it is not attached to source
releases. Details: [docs/desktop-app.md](docs/desktop-app.md).

### Optional: embeddings for semantic memory

By default there is **no** automatic model download. Memory falls back to keyword/FTS search until you set one of:

```bash
export KIROCREW_EMBED_MODEL_URL='https://…/your-model.gguf'   # https only
# or in config: memory.embed_model_url = https://…/your-model.gguf
# or in config: memory.embed_model_path = /absolute/path/to/model.gguf
```

Then restart the gateway.

## Why Vibecoders Crew

Most agent sessions end when the chat closes. Vibecoders Crew runs continuously on
hardware you control and keeps working between conversations.

**Persistent.** Sessions, memory, schedules, and task checkpoints survive
Gateway restarts, and scheduled or reactive work continues without someone at
the terminal.

**Self-learning.** Corrections and task failures become durable lessons.
Preferences and project context carry into new sessions.

**Self-evolving.** Repeated patterns become reusable skills. Memory, lessons,
and skills stay visible and editable, so each Vibecoders Crew grows more tailored to
the person and work around it.

**Runs where you choose.** Your Mac, a local container, or a remote machine
you control.

**One Gateway, many surfaces.** Work directly in the desktop app or web dashboard,
or continue the same work from the CLI and messaging surfaces like Slack and
Discord.

## What it does

| Capability | What it gives you |
|---|---|
| **Persistent sessions** | Run concurrent, isolated conversations, resume them after Gateway restarts, search prior sessions, and carry recent context into new work. |
| **Self-learning** | Turn corrections and task failures into durable lessons that change later behavior. Keep preferences, active-project context, and history scoped to the relevant workspace. Say *"no, always run the frontend checks before calling a change done"* and it becomes a workspace-scoped lesson applied in future sessions. |
| **Self-evolving skills** | Synthesize reusable skills from repeated patterns, then inspect, refine, or remove them as your work changes. |
| **Long-running tasks** | Give Vibecoders Crew a task spec and walk away. It plans steps, executes them, validates results, retries failures, and resumes from checkpoints. *"Implement this migration plan and stop if the tests fail"* runs as a checkpointed task with validation at each step. |
| **Unattended autonomy** | Run scheduled agent work or deterministic scripts and commands without a model call. Monitor work until it is done, or react to messaging events and authenticated webhooks without someone at the terminal. *"Every weekday at 9, summarize the open work I should review"* becomes a timezone-aware recurring job delivered to the surface you choose. |
| **Delegation** | Spawn isolated subagents for parallel work and bring their results back into the parent conversation. *"Research these three options in parallel and recommend one"* fans out to isolated subagents and synthesizes the tradeoffs. |
| **Work where you choose** | Work directly in the desktop app or web dashboard, or continue through the CLI and any connected messaging surface without moving the agent runtime or its state. |
| **Installable apps** | Add focused interfaces and domain workflows through dashboard pages, scoped Gateway APIs, events, and lifecycle hooks. |
| **Extensible tools** | Add MCP servers, markdown skills, and hooks without changing the core runtime. |
| **Visible execution** | Watch tool calls, subagent progress, context usage, approvals, schedules, memory, and logs from the dashboard. |
| **Defense in depth** | Combine tool approvals, OS sandboxing, sensitive-path checks, credential redaction, deny rules, audit events, and governance profiles. |

You can also paste a screenshot and ask what is causing an error. Vibecoders Crew sends
the image to the active provider model and keeps the diagnosis in the conversation
history.

The complete inventory is in [Features](docs/features.md) and
[What's New](CHANGELOG.md).

## How it works

```mermaid
flowchart TD
 S["Desktop app · Web dashboard · Slack · Telegram · WeCom · CLI"]
 G["Gateway access · sessions · memory · schedules · approvals · apps"]
 A["Agent sessions Codex App Server · optional ACP/kiro-cli · MCP tools · models"]
 S --> G --> A
```

The Gateway separates where the agent runs from where you work with it. In the
desktop app or web dashboard, you can work directly through parallel conversations,
files, task runs, approvals, memory, and apps. From Slack, Telegram, WeCom, or
the CLI, the Gateway routes your work to managed agent sessions under the same
memory, tool, approval, and policy services. Apps extend the dashboard and
Gateway APIs with focused workflows.

Each active conversation or background task uses an agent session. Its session
provider drives Codex App Server or the optional `kiro-cli` ACP runtime, streams
model and tool events, and preserves conversation state. Depending on the provider
and workload, a session is backed by its own process or by a session handle on a
shared multiplexed runtime. The Gateway manages these sessions along with
scheduling, approvals, memory, security policy, messaging connections, and the
dashboard.

The current runtime places the Gateway, agent sessions, provider processes, and state
on the same host. Run Vibecoders Crew on your Mac, inside a container on your machine,
or on a remote Linux host you control. Conversation history, memory, and
knowledge indexes remain on that host. Model requests are handled by the active
provider and follow the account and model configuration used by Codex or Kiro.

**Gateway.** The Gateway is the long-running Vibecoders Crew process. It routes
messages from the desktop app, web, CLI, and the messaging surfaces listed below. It persists
session state, injects memory and skills, starts scheduled work, coordinates
subagents, brokers approvals, enforces runtime policy, and exposes activity in
the dashboard.

**Agent sessions.** A dashboard conversation or Slack thread maps to an isolated
agent session. Scheduled jobs, task runs, Telegram and WeCom conversations, and
subagents also use managed sessions. These sessions preserve conversation
context and can run concurrently before returning results to a parent session or
configured surface.

**Provider runtimes and turns.** Vibecoders Crew supports the official Codex App
Server and the optional `kiro-cli` ACP runtime. During each turn, the session
sends a prompt, streams model and tool events, resolves approvals, and returns
the final result. An agent session is a logical isolation boundary, not
necessarily one OS process.

**Use the surface that fits the moment.**

| Surface | Best for |
|---|---|
| **Desktop app** | The simplest local experience, with a bundled Gateway plus multi-tab connections to local or remote Gateways. |
| **Web dashboard** | Parallel conversations, files, approvals, activity, memory, schedules, apps, settings, and system status at `localhost:5476`. |
| **Slack** | Work from DMs and threads with streaming replies, approvals, notifications, and session links back to the dashboard. |
| **Telegram** | Reach your agent from private DMs on your phone or laptop, with streaming replies, inline approvals, and commands. |
| **Discord** | Work from DMs with streaming replies and approvals delivered as message buttons. |
| **Teams** | Reach your agent from Microsoft Teams chats with streaming replies and approvals. |
| **Webex** | Work from Webex direct messages with streaming replies and inline approvals. |
| **WeCom** | Chat through an outbound-connected WeCom AI bot with configured user access and streaming replies. |
| **WeChat (Weixin)** | Reach your agent from WeChat with configured user access and streaming replies. |
| **CLI** | Fast interactive chat and direct automation with `kirocrew chat`, `run`, `cron`, `spawn`, and `security`. |

**Choose how work starts.**

| Mode | Use it for | Entry point |
|---|---|---|
| **Scheduled** | Briefings, audits, backups, and recurring maintenance | `kirocrew cron` or a natural-language request |
| **Proactive** | Goals that need another pass without waiting for a new user message | AutoNudge and goal-loop skills |
| **Reactive** | CI alerts, external automation, Slack activity, and other events | Authenticated agent webhooks and messaging events |
| **Task runner** | Bounded projects with explicit steps, tests, review, and checkpoint resume | `kirocrew run TASK.md` |
| **Subagents** | Independent workstreams that can run concurrently | `kirocrew spawn run "task"` |

**Memory, learning, and evolution.** Vibecoders Crew maintains preferences, active
project context, decaying history summaries, and durable lessons. Corrections
and task failures can change later behavior, while repeated patterns can become
reusable skills. In-process embeddings add semantic retrieval for memory and
the knowledge library. The stored state remains inspectable and editable
from the dashboard. Incognito and temporary session modes let you opt out when
a conversation should not persist.

**Skills, MCP, and apps.** Markdown skills supply reusable workflows and can be
loaded only when relevant. The built-in `kirocrew-core` and `kirocrew-cron` MCP
servers expose task, subagent, learning, messaging, and scheduling tools. You
can discover additional MCP servers from Kiro or Vibecoders Crew configuration. The
App Kit adds installable interfaces and domain workflows. Apps can add dashboard
pages, use scoped Gateway APIs, subscribe to events, and register lifecycle
hooks.

## Security and control

Vibecoders Crew gives an AI agent real tool access, so the controls are enforced at
the runtime boundary instead of relying only on prompt instructions.

- **Local by default.** The dashboard binds to loopback unless you explicitly
  configure a network URL. Remote dashboards require token authentication.
- **Interactive approvals.** Review tool requests in the dashboard, Slack, or
  Telegram. Session-scoped trust can reduce repeated prompts without changing
  the underlying deny and sensitive-path controls.
- **OS sandbox.** Codex sessions use the native Codex workspace sandbox. On Linux
  and macOS, the optional `kiro-cli` provider can also run inside namespace or
  Seatbelt isolation. Standard, strict, and off modes make the tradeoff explicit
  for that ACP runtime. Windows does not currently provide the additional
  KiroCrew namespace/Seatbelt layer.
- **Sensitive data guards.** Vibecoders Crew blocks direct access to protected paths,
  strips sensitive environment variables, and redacts credential patterns from
  output before it reaches a chat surface.
- **Denied operations.** 137 bundled deny patterns block destructive commands and
  common exfiltration paths even when a session has broad approval.
- **Auditability.** Security events and tool activity are recorded for review.
  Use `kirocrew security events`, `audit`, and `verify` to inspect them.
- **Governance ceiling.** Optional policy and profile files compose with a
  tightest-wins model. A running app or agent can narrow the allowed scope but
  cannot loosen the enterprise ceiling. Inspect it with `kirocrew policy show`,
  `validate`, and `explain`.

No agent security layer removes the need to protect credentials and review
high-impact actions. Avoid pasting secrets or sensitive personal data into a
chat. Read the [security architecture](docs/security-deep-dive.md) and use
[SECURITY.md](SECURITY.md) for private vulnerability reporting.

## Install, configure, and operate

**Source release.** Clone a tagged GitHub source archive for a reproducible
checkout, then build locally. The project publishes no installer, package feed,
container image, or signed desktop binary. A local wheel can be produced and
inspected with:

```bash
make wheel
python -m pip install dist/vibecoderscrew-*.whl
```

**Semantic memory.** Embeddings run in-process when a model is available. The Gateway
does not fetch a default model: configure an explicit HTTPS model URL or an absolute
local GGUF path. URL downloads are sha256-verified and stored under
`~/.kiro/crew/models`; until a model is available, memory search uses keyword/FTS
fallback and picks up embeddings automatically without a restart.

See [Installing and Building](docs/install.md) for wheels, desktop builds,
Windows, optional voice dependencies, and manual setup.

**Choose where Vibecoders Crew runs.** The current deployment model keeps the Gateway,
agent session runtime, ACP processes, and state together on one host. Your apps
and chat surfaces connect to that Gateway.

| Deployment | How to run it | Where Vibecoders Crew and its state live |
|---|---|---|
| **Mac app, local** | Build the desktop app locally with `make desktop` | The app starts its bundled Gateway. Agent sessions, ACP processes, and `~/.kiro/crew` stay on your Mac. |
| **Native local** | `make build`, or install a wheel from `make wheel` | The Gateway and agent runtime run directly on your macOS, Linux, or Windows machine. |
| **Remote hardware** | Follow the [remote host guide](docs/remote-desktop-setup.md) and install the service | The Gateway, agent sessions, and state run continuously on your Linux server, home lab, or cloud instance. Connect the desktop app or browser through an SSH tunnel. |
| **Windows source install** | Follow [the Windows guide](docs/windows-install.md) | The Gateway, agent sessions, chat, cron, and dashboard run natively with documented feature limits. |

**Keep it running.** Install a systemd service on Linux or a launchd agent on
macOS:

```bash
kirocrew service install
kirocrew service status
kirocrew logs
```

The desktop app can use this local Gateway or connect to a remote one. For an
always-on VPS, home server, or cloud VM in your account, follow the
[remote host guide](docs/remote-desktop-setup.md). Vibecoders Crew does not require a
Vibecoders Crew-hosted control plane.

**Configure it.** User data lives under `~/.kiro/crew` by default. Manage the
main configuration with `kirocrew config get`, `set`, and `edit`.

```json
{
  "agent": {
    "provider": "codex",
    "approval_mode": "interactive",
    "sandbox": "auto"
  },
  "session": {
    "timeout_secs": 1800,
    "pool_size": 2
  },
  "dashboard": {
    "bot_name": "Vibecoders Crew"
  }
}
```

`agent.provider` accepts `acp` and `codex`. The `codex` provider drives the
official Codex App Server and reuses `codex login` / the ChatGPT desktop login;
it does not require a Kiro account. Set the dashboard port with `KIROCREW_PORT` or
`kirocrew gateway --port <n>`. Slack credentials live in `~/.kiro/crew/.env`
rather than the JSON config.

```bash
kirocrew config set agent.provider codex
kirocrew config set agent.model gpt-5.6-sol
codex login status
```

**Troubleshoot quickly.** Start with `kirocrew doctor`. For an ACP timeout,
confirm `kiro-cli` is on `PATH` and logged in, then allow extra time for the
first MCP startup. For memory search, check that the embedding
model is present under `~/.kiro/crew/models` or configure `memory.embed_model_path` / a
model URL. For a stale MCP configuration, run
`kirocrew setup --agent-only`, or add `--clean` to rebuild it.

## Telemetry

VibecodersCrew collects and sends no product telemetry.

Outbound beacon, install receipts, local OpenTelemetry/JSONL product metrics,
OTLP export, and Electron profiling are hard-disabled. Legacy config values and
environment variables cannot turn them back on.

Embedding models are not fetched from any default CDN on first install. Configure
`KIROCREW_EMBED_MODEL_URL`, `memory.embed_model_url` (https), or a local
`memory.embed_model_path` if you want semantic memory; otherwise search stays on
keyword/FTS.

## Docs

| Topic | Start here |
|---|---|
| Install and packaging | [Getting started](docs/getting-started.md), [Installing and Building](docs/install.md), [Windows](docs/windows-install.md), [Desktop](docs/desktop-app.md), [Remote host](docs/remote-desktop-setup.md), [Release process](docs/release-process.md) |
| Product capabilities | [Features](docs/features.md), [Skills](skills/README.md) |
| Channels | [Slack](docs/slack-setup.md), [Discord](src/kiro_crew/docs/discord-integration.md), [Telegram](src/kiro_crew/docs/telegram-integration.md), [Teams](src/kiro_crew/docs/teams-integration.md), [Webex](src/kiro_crew/docs/webex-integration.md), [WeCom](src/kiro_crew/docs/wecom-integration.md), [WeChat (Weixin)](src/kiro_crew/docs/weixin-integration.md) |
| Architecture | [System architecture](docs/project-architecture.md), [Memory](docs/memory-architecture.md), [MCP](docs/mcp-architecture.md), [App Kit](docs/app-kit/getting-started.md) |
| Trust and dependencies | [Security](docs/security-deep-dive.md), [Security policy](SECURITY.md) |
| Project work | [Contributing](CONTRIBUTING.md), [Tenets](TENETS.md), [Governance](GOVERNANCE.md), [Maintainers](MAINTAINERS.md), [AI assistant rules](AGENTS.md), [Changelog](CHANGELOG.md) |

Contributions are welcome. Create a branch from `codex-main`, keep changes focused,
and run the relevant checks before opening a pull request:

```bash
# Backend
pip install -e ".[voice]" --group dev
pytest

# Frontend
cd website
npm ci
npm run check
npm run build
```

Use [GitHub Issues](https://github.com/serejaris/vibecoderscrew/issues) for bugs and
feature requests. Do not file security vulnerabilities publicly.

## Contributors

Vibecoders Crew was made possible by its internal community, the people who supported the
project and shipped its code, together with everyone who has since opened a pull
request in the open. This is that founding group; as Vibecoders Crew grows in the open, we
look forward to many more contributors joining them. Thank you to everyone who helped
make this tool possible:

Listed alphabetically by GitHub username. Internal contributors appear here if they
consented to public recognition in the contributor survey; open-source contributors are
included from this repository's pull request history. If you contributed and would like
to be added, corrected, or removed, please open an issue or a pull request.

## License

Vibecoders Crew is licensed under the [Apache License 2.0](LICENSE). See
[NOTICE](NOTICE) for upstream attribution and the modification
notice.

## Credits

VibecodersCrew is based on [Kiro Crew](https://github.com/kirodotdev/KiroCrew)
(Apache-2.0). See [NOTICE](NOTICE) and [MODIFICATIONS.md](MODIFICATIONS.md).

vibecoderscrew

vibecoderscrew Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vibecoderscrew

vibecoderscrew Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README