banteg
228 lines
6.1 KiB
Markdown
228 lines
6.1 KiB
Markdown
# Projects and branches
|
|
|
|
This tutorial shows you how to register repos as projects and run tasks on feature branches without switching directories.
|
|
|
|
**What you'll learn:** How to target repos from anywhere with `/<project-alias>`, and run on branches with `@branch`.
|
|
|
|
## The problem
|
|
|
|
So far, Takopi runs in whatever directory you started it. If you want to work on a different repo, you have to:
|
|
|
|
1. Stop Takopi
|
|
2. `cd` to the other repo
|
|
3. Restart Takopi
|
|
|
|
Projects fix this. Once you register a repo, you can target it from chat—even while Takopi is running elsewhere.
|
|
|
|
## 1. Register a project
|
|
|
|
Navigate to the repo and run `takopi init`:
|
|
|
|
```sh
|
|
cd ~/dev/happy-gadgets
|
|
takopi init happy-gadgets
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
saved project 'happy-gadgets' to ~/.takopi/takopi.toml
|
|
```
|
|
|
|
This adds an entry to your config (Takopi also fills in defaults like `worktrees_dir`, `default_engine`, and sometimes `worktree_base`):
|
|
|
|
=== "takopi config"
|
|
|
|
```sh
|
|
takopi config set projects.happy-gadgets.path "~/dev/happy-gadgets"
|
|
```
|
|
|
|
=== "toml"
|
|
|
|
```toml
|
|
[projects.happy-gadgets]
|
|
path = "~/dev/happy-gadgets"
|
|
```
|
|
|
|
!!! tip "Project aliases are also Telegram commands"
|
|
The alias becomes a `/command` you can use in chat. Keep them short and lowercase: `myapp`, `backend`, `docs`.
|
|
|
|
## 2. Target a project from chat
|
|
|
|
Now you can start Takopi from another repo. If you don't specify a project, Takopi runs in the directory where you launched it.
|
|
|
|
```sh
|
|
cd ~/dev/your-project
|
|
takopi
|
|
```
|
|
|
|
And target the project by prefixing your message:
|
|
|
|
!!! user "You"
|
|
/happy-gadgets explain the authentication flow
|
|
|
|
Takopi runs the agent in `~/dev/happy-gadgets`, not your current directory.
|
|
|
|
The response includes a context footer:
|
|
|
|
!!! takopi "Takopi"
|
|
ctx: happy-gadgets<br>
|
|
codex resume abc123
|
|
|
|
That `ctx:` line tells you which project is active. When you reply, Takopi automatically uses the same project—you don't need to repeat `/happy-gadgets`.
|
|
|
|
## 3. Set up worktrees
|
|
|
|
Worktrees let you run tasks on feature branches without touching your main checkout. Instead of `git checkout`, Takopi creates a separate directory for each branch.
|
|
|
|
Add worktree config to your project:
|
|
|
|
=== "takopi config"
|
|
|
|
```sh
|
|
takopi config set projects.happy-gadgets.path "~/dev/happy-gadgets"
|
|
takopi config set projects.happy-gadgets.worktrees_dir ".worktrees"
|
|
takopi config set projects.happy-gadgets.worktree_base "main"
|
|
```
|
|
|
|
=== "toml"
|
|
|
|
```toml
|
|
[projects.happy-gadgets]
|
|
path = "~/dev/happy-gadgets"
|
|
worktrees_dir = ".worktrees" # where branches go
|
|
worktree_base = "main" # base for new branches
|
|
```
|
|
|
|
!!! note "Ignore the worktrees directory"
|
|
Add `.worktrees/` to your global gitignore so it doesn't clutter `git status`:
|
|
```sh
|
|
echo ".worktrees/" >> ~/.config/git/ignore
|
|
```
|
|
|
|
## 4. Run on a branch
|
|
|
|
Use `@branch` after the project:
|
|
|
|
!!! user "You"
|
|
/happy-gadgets @feat/new-login add rate limiting to the login endpoint
|
|
|
|
Takopi:
|
|
1. Checks if `.worktrees/feat/new-login` exists (and is a worktree)
|
|
2. If the branch exists locally, it adds a worktree for it
|
|
3. If the branch doesn't exist, it creates it from `worktree_base` (or the repo default) and adds the worktree
|
|
4. Runs the agent in that worktree
|
|
|
|
The response shows both project and branch:
|
|
|
|
!!! takopi "Takopi"
|
|
ctx: happy-gadgets @feat/new-login<br>
|
|
codex resume xyz789
|
|
|
|
Replies stay on the same branch. Your main checkout is untouched.
|
|
|
|
## 5. Context persistence
|
|
|
|
Once you've set a context (via `/<project-alias> @branch` or by replying), it sticks:
|
|
|
|
!!! user "You"
|
|
/happy-gadgets @feat/new-login add tests
|
|
|
|
!!! takopi "Takopi"
|
|
ctx: happy-gadgets @feat/new-login
|
|
|
|
!!! user "reply to the bot's answer"
|
|
also add integration tests
|
|
|
|
!!! takopi "Takopi"
|
|
ctx: happy-gadgets @feat/new-login
|
|
|
|
The `ctx:` line in each message carries the context forward.
|
|
|
|
## 6. Set a default project
|
|
|
|
If you mostly work in one repo, set it as the default:
|
|
|
|
=== "takopi config"
|
|
|
|
```sh
|
|
takopi config set default_project "happy-gadgets"
|
|
```
|
|
|
|
=== "toml"
|
|
|
|
```toml
|
|
default_project = "happy-gadgets"
|
|
```
|
|
|
|
Now messages without a `/<project-alias>` prefix go to that repo:
|
|
|
|
!!! user "You"
|
|
add a health check endpoint
|
|
|
|
Goes to `happy-gadgets` automatically.
|
|
|
|
## Putting it together
|
|
|
|
Here's a typical workflow:
|
|
|
|
```sh
|
|
takopi
|
|
```
|
|
|
|
!!! user "You"
|
|
/happy-gadgets review the error handling
|
|
|
|
!!! user "You"
|
|
/happy-gadgets @feat/caching implement caching
|
|
|
|
!!! takopi "Takopi"
|
|
ctx: happy-gadgets @feat/caching
|
|
|
|
!!! user "You"
|
|
also add cache invalidation
|
|
|
|
!!! user "You"
|
|
/backend @fix/memory-leak profile memory usage
|
|
|
|
!!! user "You"
|
|
/happy-gadgets bump the version number
|
|
|
|
All from the same Telegram chat, without restarting Takopi or changing directories.
|
|
|
|
## Project config reference
|
|
|
|
Full options for `[projects.<alias>]`:
|
|
|
|
| Key | Default | Description |
|
|
|-----|---------|-------------|
|
|
| `path` | (required) | Repo root. Expands `~`. |
|
|
| `worktrees_dir` | `.worktrees` | Where branch worktrees are created (relative to the project path). |
|
|
| `worktree_base` | `null` | Base branch for new worktrees. If unset, Takopi uses `origin/HEAD`, the current branch, or `master`/`main` (in that order). |
|
|
| `default_engine` | `null` | Engine to use for this project (overrides global default). |
|
|
| `chat_id` | `null` | Bind a Telegram chat/group to this project. |
|
|
|
|
## Troubleshooting
|
|
|
|
**"unknown project"**
|
|
|
|
Run `takopi init <alias>` in the repo first.
|
|
|
|
**Branch worktree not created**
|
|
|
|
Make sure the worktrees directory (default `.worktrees`) is writable. If you've customized `worktrees_dir`, verify that path exists or can be created.
|
|
|
|
**Context not carrying forward**
|
|
|
|
Make sure you're **replying** to a message with a `ctx:` line. If you send a new message (not a reply), context resets unless you have a `default_project`.
|
|
|
|
**Worktree conflicts with existing branch**
|
|
|
|
If the branch already exists locally, Takopi uses it. For a fresh start, delete the worktree **and** the branch, or pick a new branch name.
|
|
|
|
## Next
|
|
|
|
You've got projects and branches working. The final tutorial covers using multiple engines effectively.
|
|
|
|
[Multi-engine workflows →](multi-engine.md)
|