commit	6d3de48ec0ec2fb8f194a11f1711b7128b7d1699	[log] [tgz]
author	philip.zeyliger <philip.zeyliger@gmail.com>	Tue Jun 10 19:38:14 2025 -0700
committer	Philip Zeyliger <philip@bold.dev>	Tue Jun 10 19:40:16 2025 -0700
tree	14325a290001d13a482c116c83ee0b87aa7e36c5
parent	a1762b94e6ddf5db0a0f6b7a5104fa236855320b [diff]

feat: add -link-to-github flag with Octocat icon for GitHub branch linking

Add internal flag to enable GitHub branch linking in both termui and webui
interfaces, displaying clickable Octocat icons next to copy icons for pushed
branches when working with GitHub repositories.

Problem Analysis:
When sketch pushes branches to GitHub repositories, users had no direct way to
navigate from the sketch interface to view those branches on GitHub. Branch
names were displayed as plain text in both terminal and web interfaces,
requiring users to manually construct GitHub URLs or switch to external tools
to view their pushed changes on the GitHub platform.

This created friction in the workflow, especially for teams collaborating on
GitHub where quick access to branch views, pull request creation, and code
review processes are essential parts of the development workflow.

Implementation Changes:

1. Command Line Flag Infrastructure:
   - Added linkToGitHub bool field to CLIFlags struct
   - Configured -link-to-github as internal flag with false default
   - Integrated flag passing through ContainerConfig and AgentConfig chains
   - Added flag to dockerimg launch command arguments for container mode

2. Agent Interface Enhancement:
   - Added LinkToGitHub() method to CodingAgent interface
   - Implemented method in Agent struct returning config.LinkToGitHub
   - Extended State struct with link_to_github JSON field (with omitempty)
   - Updated getState() function to include agent's GitHub linking preference
   - Updated mockAgent in tests to support new LinkToGitHub() method

3. Terminal UI GitHub Integration:
   - Added isGitHubRepo() method with regex pattern matching for GitHub URLs
   - Implemented getGitHubBranchURL() for constructing GitHub branch links
   - Enhanced commit message display to show GitHub URLs when flag enabled
   - Updated exit summary to include GitHub links for single and multiple branches
   - Added regex import for GitHub URL pattern validation

4. Web UI TypeScript Integration:
   - Added link_to_github field to State interface in types.ts
   - Enhanced formatGitHubRepo() method to return owner/repo extraction
   - Implemented getGitHubBranchLink() helper in container status component
   - Created parallel helper methods in timeline message component

5. Container Status Component Updates:
   - Added commit-info-container with flexbox layout for proper alignment
   - Implemented layout: Branch Text → Copy Icon → Octocat Icon
   - Added 16px clipboard copy icon with opacity states (70% default, 100% on hover)
   - Integrated 16px Octocat SVG icon as clickable GitHub link
   - Maintained existing copyCommitInfo click functionality for branch text

6. Timeline Message Component Enhancement:
   - Added commit-branch-container for consistent layout structure
   - Implemented same layout pattern: Branch Text → Copy Icon → Octocat Icon
   - Added 14px clipboard and Octocat icons matching timeline scale
   - Enhanced CSS with hover states and proper alignment
   - Preserved existing copyToClipboard functionality for branch text clicks

7. Data Flow Integration:
   - Updated sketch-timeline component to pass state to message components
   - Modified sketch-app-shell to provide containerState to timeline
   - Ensured proper state propagation through component hierarchy
   - Maintained backward compatibility with existing state management

Technical Details:
- GitHub URL detection supports HTTPS, SSH, and git protocol formats
- Regex patterns: ^https://github\.com/, ^git@github\.com:, ^git://github\.com/
- Link format: https://github.com/{owner}/{repo}/tree/{branch-name}
- Internal flag prevents exposure in user-visible help documentation
- SVG Octocat uses official GitHub icon design with 16-point grid
- Copy icons use standard clipboard SVG with overlapping rectangles design
- Event propagation properly stopped to prevent interference with copy actions
- Conditional rendering ensures icons only appear when GitHub links available
- Flexbox layout ensures proper alignment across different screen sizes
- CSS transitions provide smooth hover state animations

Benefits:
- Direct navigation from sketch UI to GitHub branch views
- Seamless integration with GitHub-based development workflows
- Enhanced productivity for teams using GitHub collaboration features
- Clear functional separation: text copy vs external GitHub link
- Familiar clipboard icon reinforces copy functionality
- Improved visual hierarchy guides user interaction patterns
- Maintains existing copy-to-clipboard functionality as fallback
- Zero impact on non-GitHub repositories or when flag disabled
- Consistent experience across terminal and web interfaces
- Enhanced accessibility with distinct click targets and hover states

Testing:
- Verified flag parsing and configuration propagation through all layers
- Confirmed GitHub URL detection works with various GitHub URL formats
- Tested conditional rendering in both web UI components
- Validated CSS styling and hover effects for GitHub branch links
- Ensured backward compatibility with non-GitHub repositories
- Verified TypeScript compilation with new template structures
- Confirmed proper icon positioning and spacing in test layouts
- Validated hover states and opacity transitions function correctly
- All Go tests and TypeScript compilation successful

This enhancement bridges the gap between sketch's development environment and
GitHub's collaboration platform, enabling more efficient workflows for teams
using GitHub repositories while preserving full functionality for other Git
hosting solutions. The visual design provides intuitive flow from local
operations (copy) to external actions (GitHub), creating a more organized
and user-friendly interface for branch management workflows.

Co-Authored-By: sketch <hello@sketch.dev>
Change-ID: s1c083b45b5401c2bk

12 files changed

tree: 14325a290001d13a482c116c83ee0b87aa7e36c5

README.md

Sketch

Sketch is an agentic coding tool. It draws the 🦉

🚀 Overview

Sketch runs in your terminal, has a web UI, understands your code, and helps you get work done. To keep your environment pristine, sketch starts a docker container and outputs its work onto a branch in your host git repository.

Sketch helps with most programming environments, but Sketch has extra goodies for Go.

📋 Quick Start

go install sketch.dev/cmd/sketch@latest
sketch

🔧 Requirements

Currently, Sketch runs on macOS and Linux. It uses Docker for containers.

Platform	Installation
macOS	`brew install colima` (or Docker Desktop/Orbstack)
Linux	`apt install docker.io` (or equivalent for your distro)
WSL2	Install Docker Desktop for Windows (docker entirely inside WSL2 is tricky)

The sketch.dev service is used to provide access to an LLM service and give you a way to access the web UI from anywhere.

🤝 Community & Feedback

Discord: Join our community at https://discord.gg/6w9qNRUDzS
GitHub Issues: Submit feedback at https://github.com/boldsoftware/sketch/issues

📖 User Guide

Getting Started

Start Sketch by running sketch in a Git repository. It will open your browser to the Sketch chat interface, but you can also use the CLI interface. Use -open=false if you want to use just the CLI interface.

Ask Sketch about your codebase or ask it to implement a feature. It may take a little while for Sketch to do its work, so hit the bell (🔔) icon to enable browser notifications. We won't spam you or anything; it will notify you when the Sketch agent's turn is done, and there's something to look at.

How Sketch Works

When you start Sketch, it:

Creates a Dockerfile
Builds it
Copies your repository into it
Starts a Docker container with the "inside" Sketch running

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.

Sketch's agentic loop uses tool calls (mostly shell commands, but also a handful of other important tools) to allow the LLM to interact with your codebase.

Getting Your Git Changes Out

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/*.

Finding Sketch branches:

git branch -a --sort=creatordate | grep sketch/ | tail

The UI keeps track of the latest branch it pushed and displays it prominently. You can use standard Git workflows to pull those branches into your workspace:

git cherry-pick $(git merge-base origin/main sketch/foo)

or merge the branch

git merge sketch/foo

or reset to the branch

git reset --hard sketch/foo

Ie use the same workflows you would if you were pulling in a friend's Pull Request.

Advanced: You can ask Sketch to git fetch sketch-host and rebase onto another commit. This will also fetch where you started Sketch, and we do a bit of "git fetch refspec configuration" to make origin/main work as a git reference.

Don't be afraid of asking Sketch to help you rebase, merge/squash commits, rewrite commit messages, and so forth; it's good at it!

Reviewing Diffs

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

Connecting to Sketch's Container

You can interact directly with the container in three ways:

Web UI Terminal: Use the "Terminal" tab in the UI
SSH: Look at the startup logs or click the information icon to see a command like ssh sketch-ilik-eske-tcha-lott. We have automatically configured your SSH configuration to make these special hostnames work.
Visual Studio Code: Look for a command line or magic link behind the information icon, or when Sketch starts up. This starts a new VSCode session "remoted into" the container. You can edit the code, use the terminal, review diffs, and so forth.

Using SSH (and/or VSCode) allows you to forward ports from the container to your machine. For example, if you want to start your development webserver, you can do something like this:

# Forward container port 8888 to local port 8000
ssh -L8000:localhost:8888 sketch-ilik-epor-tfor-ward go run ./cmd/server

This makes http://localhost:8000/ on your machine point to localhost:8888 inside the container.

Using Browser Tools

You can ask Sketch to browse a web page and take screenshots. There are tools both for taking screenshots and "reading images", the latter of which sends the image to the LLM. This functionality is handy if you're working on a web page and want to see what the in-progress change looks like.

❓ FAQ

"No space left on device"

Docker images, containers, and so forth tend to pile up. Ask Docker to prune unused images and containers:

docker system prune -a

🛠️ Development

See CONTRIBUTING.md for development guidelines.

📄 Open Source

Sketch is open source. It is right here in this repository! Have a look around and mod away.

If you want to run Sketch entirely without the sketch.dev service, you can set the flag -skaband-addr="" and then provide an ANTHROPIC_API_KEY environment variable. (More LLM services coming soon!)