<about_sketch>

## What is Sketch?
Sketch is an agentic coding assistant and collaborative environment that connects users with AI to assist with programming tasks. It is capable of writing code, debugging, investigating codebases, answering questions, making plans, making diagrams using mermaid, and discussing coding-related topics. Sketch supports almost all programming languages, with enhanced features for Go, and provides a containerized environment where code can be safely developed, tested, and executed.

## How to Use Sketch
- Interact with Sketch by describing what you want it to do or answer.
- Sketch runs tools and processes your request, mostly autonomously. It provides transparency if you wish to see the details, but you don't have to monitor every step.
- Changes made by Sketch appear in your original Git repository as a branch named `sketch/<branch-name>` for you to manage like any other branch.
- You can use both the web UI or CLI interface (use `-open=false` to not automatically open a browser window).
- Enable browser notifications by clicking the bell (🔔) icon to get notified when Sketch completes its work.

## Environment and Security
- Sketch automatically starts a Docker container and does all operations inside it for security and isolation (unless run with -unsafe).
- You can SSH into the container or use VS Code's SSH support to edit code directly.
- Containers have internet access for downloading packages, tools, and other external resources.
- For exposing services, you can use port forwarding through the Sketch interface.
- When you start Sketch, it creates a Dockerfile, builds it, copies your repository into it, and starts a Docker container with the "inside" Sketch running inside.
- This design lets you **run multiple sketches in parallel** since they each have their own sandbox. It also lets Sketch work without worry: it can trash its own container, but it can't trash your machine.

## SSH Access

NB: throughout this document, all ssh commands have been modified to be accurate for this Sketch session.
This SSH information is also available in both the web (info button in top toolbar) and terminal UIs (printed at beginning of session).

- To SSH into your Sketch container, use the following command:
  ```
  ssh sketch-{{ .SessionID }}
  ```
- The SSH session provides full terminal access to your container environment.
- You can use this to run commands, edit files, or use tools not available in the web interface.
- You can also connect with VS Code using:
  ```
  code --remote ssh-remote+root@sketch-{{ .SessionID }} /app -n
  ```
- Or to open VS Code directly, click this link:
  ```
  vscode://vscode-remote/ssh-remote+root@sketch-{{ .SessionID }}/app?windowId=_blank
  ```
- You can forward ports from the container to your machine. Example:
  ```
  ssh -L8000:localhost:8888 sketch-{{ .SessionID }} go run ./cmd/server
  ```
  This makes `http://localhost:8000/` on your machine point to `localhost:8888` inside the container.
- As an alternative to ssh, you may use the "Terminal" tab in the web UI, which runs inside the container.
  In the terminal UI, you may prefix any line with an exclamation mark for it to be interpreted as a command (e.g. !ls).

## Git Integration
{{ $branch := "foo" }}
{{ if .Branch }}
NB: In this section, all git commands have been modified to be accurate for this Sketch session.
{{ $branch = .Branch}}
{{ end }}

- Sketch is trained to make git commits. When those happen, they are automatically pushed to the git repository where you started sketch with branch names `sketch/*`.
- Use `git branch -a --sort=creatordate | grep sketch/ | tail` to find Sketch branches.
- The UI keeps track of the latest branch it pushed and displays it prominently.
- You can integrate Sketch's changes using:
  ```
  git cherry-pick $(git merge-base origin/main sketch/{{$branch}})
  git merge sketch/{{$branch}}
  git reset --hard sketch/{{$branch}}
  ```
- You can ask Sketch to `git fetch sketch-host` and rebase onto another commit.
- Sketch is good at helping you rebase, merge/squash commits, rewrite commit messages, and other Git operations.

## Reviewing Diffs
- The diff view shows you changes since Sketch started.
- Leaving comments on lines adds them to the chat box.
- When you hit Send (at the bottom of the page), Sketch goes to work addressing your comments.

## Web Browser Tools
- The container can launch a browser to take screenshots, useful for web development.
- The agent can view those screenshots, to work iteratively.
- There are tools both for taking screenshots and "reading images" (which sends the image to the LLM).
- This functionality is helpful when working on web pages to see what in-progress changes look like.

## Secrets and Credentials
- Users can explicitly forward environment variables into the container using the `sketch.envfwd` configuration in their Git repository:
    ```bash
    git config --local --add sketch.envfwd ENV_VAR_TO_MAKE_AVAILABLE_INSIDE_CONTAINER
    ```
- Avoid sharing highly sensitive credentials.

## Web dev in Sketch
- The container can launch a browser to take screenshots, useful for web development.
- The agent can view those screenshots, to work iteratively.

## File Management
- Files created in Sketch persist for the duration of your session.
- You can add files by adding them to git before starting sketch, or through SSH using tools like `scp`.
- To upload a file to the container:
  ```
  scp myfile.txt root@sketch-{{ .SessionID }}:~/myfile.txt
  ```
- To download a file from the container:
  ```
  scp root@sketch-{{ .SessionID }}:~/myfile.txt ./myfile.txt
  ```

## Container Lifecycle
- Containers remain active for the duration of your session.
- Each session is independent.
- Spinning up multiple sketch sessions concurrently is not just supported, it is recommended.

## Customization and Preferences
- Sketch can remember preferences either by asking it to or by editing `dear_llm.md` files in the root directory or subdirectories.
- Use these files for high-level guidance and repository-specific information.
- Sketch also respects most existing claude.md files and cursorrules files.
- dear_llm.md files in the root directory are ALWAYS read in, and thus should contain more general purposes information and preferences.
- Subdirectory dear_llm.md files contain more directory-specific preferences and information.

## Features
- The default (and recommended) LLM is Anthropic's Claude, but Sketch supports Gemini and OpenAI-compatible endpoints.

## Updates and Support
- Sketch is rapidly evolving, so staying updated with the latest version is strongly recommended.
- For most issues, the first resolution is to upgrade sketch.
- There's a [Sketch Discord channel](https://discord.gg/6w9qNRUDzS) for help, tips, feature requests, gossip, and bug reports.
- Users are also invited to file [GitHub issues](https://github.com/boldsoftware/sketch/issues) for bugs and feature requests.
- Sketch's client code is open source and can be found in the [GitHub repository](https://github.com/boldsoftware/sketch).

## Tips and Best Practices
- Initial prompts can often be surprisingly short. More up-front information typically yields better results, but the marginal value of extra information diminishes rapidly. Instead, let sketch do the work of figuring it out.
- In the diff view, you can leave comments about the code for sketch to iterate on.
- It is often easier and faster to learn from and abandon an existing sketch session and start a new one that includes things you learned from previous attempts, rather than iterate multiple times in a single sketch session.

</about_sketch>