**English** | [Русский](/ru/docs/quickstart) # Quick Start TAUSIK — **T**ask **A**gent **U**nified **S**upervision, **I**nspection & **K**nowledge. Step-by-step guide: from zero to your first task with an AI agent. Takes 10-15 minutes. No prior experience with AI tools required. > **Are you the agent?** Read [agent-quickstart.md](/docs/agent-quickstart) > instead — the same path as exact calls, with the replies and refusals you > will see, for every host bootstrap scaffolds. --- ## Step 0. What You'll Need Make sure the following are installed on your computer: 1. **Python 3.11 or newer** - Windows: download from [python.org](https://www.python.org/downloads/), check "Add to PATH" during installation. Alternative: `winget install Python.Python.3.13` - macOS: `brew install python@3.13` - Linux (Ubuntu/Debian): `sudo apt install python3.13` · Fedora: `sudo dnf install python3.13` - Verify: open a terminal and type `python --version` (should show 3.11+) - Bootstrap will automatically create an isolated virtual environment (`.tausik/venv/`) and install all required dependencies. Your system Python will not be modified. If a suitable Python is not found, bootstrap will show download instructions. 2. **Git** - Windows: download from [git-scm.com](https://git-scm.com/downloads) - macOS: `brew install git` - Linux: `sudo apt install git` - Verify: `git --version` 3. **Visual Studio Code** - Download from [code.visualstudio.com](https://code.visualstudio.com/) 4. **AI IDE — one of the following:** - **Claude Code** — VSCode extension or CLI: `npm install -g @anthropic-ai/claude-code` - **Cursor** — download from [cursor.com](https://cursor.com) - **Qwen Code (GigaCode)** — install from [qwen.ai/qwencode](https://qwen.ai/qwencode) - **Kilo Code** — VSCode addon; pairs with z.ai GLM models (see [Kilo + z.ai](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/en/kilo-zai.md)) - **OpenCode** — `npm i -g opencode-ai`; bootstrap with `--ide opencode` - **Codex CLI** — bootstrap with `--ide codex`; its hooks enforce only after you trust them in Codex (see [model-providers.md](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/en/model-providers.md#codex-enforcement-matrix)) - **Windsurf** — download from [windsurf.com](https://windsurf.com) (expected; not scaffolded by bootstrap) - You'll need an API key or subscription for your chosen IDE ## Step 1. Create a Repository Go to [github.com](https://github.com) (or GitLab, Bitbucket — any Git hosting). 1. Click **New Repository** 2. Name it, for example: `my-project` 3. Check "Add a README file" 4. Click **Create Repository** Now clone the repository to your computer: ```bash git clone https://github.com/your-username/my-project.git cd my-project ``` > If you already have a project — skip this step and navigate to your project folder. ## Step 2. Connect TAUSIK > **Already have a project with code?** See [Migrating an Existing Project](#migrating-an-existing-project) below — TAUSIK merges into your setup without overwriting anything. There are two ways — tell your AI agent, or do it manually. We recommend the first. ### Option A: Tell your agent (easiest) Open your project in the IDE, open your AI agent (Claude Code, Cursor, Qwen Code, Windsurf) and write: ``` Add https://github.com/Kibertum/tausik-core as a git submodule in .tausik-lib, run python .tausik-lib/bootstrap/bootstrap.py --init, add .tausik/ to .gitignore ``` The agent will execute all three steps — you just confirm its actions. ### Option B: Manually via terminal If you prefer doing everything by hand: ```bash # Connect TAUSIK as a Git submodule # (A submodule is a reference to another Git repository inside yours — # it keeps TAUSIK's code linked but separate from your project) git submodule add https://github.com/Kibertum/tausik-core .tausik-lib # Run bootstrap (one command does everything) # Project name is auto-derived from the directory name python .tausik-lib/bootstrap/bootstrap.py --init # Add working data to .gitignore echo ".tausik/" >> .gitignore ``` ### Restart Your IDE **After bootstrap, restart your IDE window** (Claude Code, Cursor, Qwen Code, Windsurf). Bootstrap generates project MCP configs (`.mcp.json` for Claude ecosystem and `.cursor/mcp.json` for Cursor), but IDEs load them only on startup. Without restart, the agent may fall back to CLI mode instead of using MCP tools. > **Qwen Code users:** Bootstrap also creates `.qwen/settings.json` with MCP config and `QWEN.md` with project instructions. Use `--ide qwen` if you only use Qwen Code, or `--ide all` for multi-IDE setups. ### What Happens After Bootstrap Regardless of which option you chose — the result is the same: - A `.tausik/` folder appears — database, scripts, configuration - A `.claude/` folder appears — skills and settings for Claude Code - A `CLAUDE.md` file appears — instructions for the AI agent - TAUSIK detects your project's stack (Python, React, Go, etc.) and enables appropriate checks **Two directories to understand:** - **`.tausik-lib/`** — the framework source code (git submodule, tracked in version control). This is TAUSIK itself. - **`.tausik/`** — runtime data: database, config, virtual environment. Added to `.gitignore` — this is local working data, never committed. Team members who clone the repo just need to run `git submodule update --init` to get the framework, then `python .tausik-lib/bootstrap/bootstrap.py --init` to set up their local `.tausik/`. `.claude/` and `CLAUDE.md` — keep these under version control. These are instructions for the agent, they should be in the repository. ## Step 3. Verify Installation ```bash .tausik/tausik status ``` > **Windows note:** This command requires Git Bash or WSL. If you're using cmd.exe or PowerShell, run `.tausik/tausik.cmd status` instead. If you see something like: ``` Tasks: 0/0 done Session: none Epics: 0 ``` Everything is working. TAUSIK is ready. ## Step 4. Open the Project in VSCode ```bash code . ``` VSCode will open with your project. In the side panel or at the bottom you'll see Claude Code — a chat with the AI agent. If Claude Code doesn't appear — check that the extension is installed (Ctrl+Shift+X → "Claude Code"). ## Step 5. Start a Session Write in the Claude Code chat: ``` start working ``` The agent will open a session, show the project status, and suggest what to work on. On the first run the project is empty — that's normal. ## Step 6. Create Your First Task Simply describe what needs to be done, in your own words: ``` create a landing page with the title "My Project" and a "Get Started" button ``` The agent will: 1. Create a task in the database 2. Formulate a goal and acceptance criteria (what counts as "done") — **including at least one error or boundary case**. TAUSIK's Context Gate (QG-0) requires it, and the agent supplies it for you (e.g. "the button stays disabled until the title is filled"). You don't have to write it; just know the agent will add one. 3. Start working — write code, create files You'll see the agent working: creating files, writing code, verifying everything works. You can intervene at any time — provide clarification, ask to change the approach. ## Step 7. Complete the Task When the agent finishes (or you decide the result is satisfactory), write: ``` done, ship it ``` The agent will: 1. Run **`tausik verify`** — heavy verification step (pytest, tsc, cargo, phpstan, etc.). May take minutes on large projects. The result is **cached**. 2. Verify that the acceptance criteria are met 3. Close the task via **`task done`** — lightweight step (milliseconds), looks up the fresh verify cache. 4. Offer to commit the changes Answer "yes" to the commit offer — and your first task is complete. If the agent's IDE times out long tool calls (the VS Code extension cuts at about 60 seconds), keep the two steps apart: `tausik verify --task ` first, then `task done`, which reads the cached result in milliseconds. Settings that change this flow — the size of the rules file, a terse output style, the host profile — are in **[Configuration](/docs/configuration#settings-met-in-the-quick-start)**. ## Step 8. Wrap Up When you're done working for the day: ``` that's all for today ``` The agent will save context: what was done, what's unfinished, what decisions were made. Next time you say "start working" — the agent will load this context and continue from where you left off. --- ## Full Work Cycle Here's what typical work with TAUSIK looks like after setup: ``` You: "start working" → agent opens a session You: "fix the bug — form doesn't submit" → agent creates a task, starts ... agent works ... You: "done, ship it" → agent verifies, commits You: "one more — add email validation" → next task ... agent works ... You: "done, ship it" → verify, commit You: "that's all for today" → agent saves context ``` Two or three messages per task. Everything else — automatic. --- ## Working With a Team `.tausik/` is gitignored — the database is yours. What your teammates need is the project's *knowledge*, and that travels in git as text: tasks, decisions and memory are exported to a readable `tausik/` tree that you commit alongside the code. ```bash tausik state export # DB → tausik/ (runs automatically on any durable write) git add tausik/ && git commit ``` After pulling someone else's work, bring it into your database: ```bash git pull tausik sync # tausik/ → DB, files win ``` A teammate who clones the repository gets the project's history rather than an empty database, and no external store has to exist for that to work. `tausik status` tells you when the tree and the database disagree. It reports the counts and names both directions — `tausik sync` (tree → DB) and `tausik state export` (DB → tree) — without recommending either, because the counts prove the two sides *differ*, not which one is newer. Rows the tree has and the database lacks are the one unambiguous signal, and that is what you see after a `git pull`. **[Full round-trip contract →](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/en/team-state-in-git.md)** --- ## Troubleshooting **"command not found: .tausik/tausik"** - On Windows use Git Bash or WSL, not cmd.exe - Or call directly: `.tausik/tausik.cmd status` **"Python not found"** - Make sure Python is in PATH: `python --version` - On some systems the command is `python3` **"Claude Code doesn't see skills"** - Restart VSCode after bootstrap - Make sure `.claude/` is created and not empty **"Database is locked"** - Delete the file `.tausik/tausik.db-wal` and try again - This happens if a previous process terminated incorrectly **Agent doesn't create tasks, just writes code** - Check that `CLAUDE.md` exists in the project root - Check that it contains a "Constraints" section with the "No code without a task" rule --- ## Migrating an Existing Project If you already have a project with code and want to add TAUSIK: 1. **Navigate to your project root** and connect TAUSIK as a submodule: ```bash git submodule add https://github.com/Kibertum/tausik-core .tausik-lib python .tausik-lib/bootstrap/bootstrap.py --init ``` 2. **Bootstrap auto-detects your environment:** - Recognizes your stack (Python, React, Go, etc.) and enables matching quality gates - Detects existing config files (`.eslintrc`, `pyproject.toml`, etc.) - Preserves your existing `.gitignore`, `CLAUDE.md`, `.mcp.json`, and `.cursor/mcp.json` — merges instead of overwriting 3. **What gets tracked in git:** - `.tausik-lib/` — the framework itself (git submodule, tracked) - `.tausik/` — runtime data (database, config, venv) — added to `.gitignore`, never committed - `.claude/` and `CLAUDE.md` — agent instructions, tracked 4. **Starting fresh vs. importing:** - TAUSIK starts with a clean task database. There is no automatic import from other systems. - If you have existing tasks, create them manually with `task quick "title"` or plan them with `/plan`. - Your code history stays in git — TAUSIK only manages the AI workflow layer on top. After setup, verify with `.tausik/tausik status` and start working normally. --- ## What's Next You've mastered the basic cycle. Next you can learn more about: - **[Workflow](/docs/workflow)** — quick and full modes, quality gates, memory - **[Skills](/docs/skills)** — all phrases the agent understands - **[CLI Commands](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/en/cli.md)** — if you want to call TAUSIK from the terminal directly