Install Lens

MachAI Lens is a desktop app that works on the timing reports your existing flow already produces. To see what it does with them, read What Lens does.

Today Lens is delivered as source code: you are given access to the chipcopilot repository on GitHub, and you run Lens from a copy of it with Python. There is no installer or packaged app yet. The steps below are the same ones the Lens team uses.

Requirements

Operating system. macOS is the primary tested platform. Linux and Windows are supported in the code but are less exercised, so expect rough edges there and tell us about them.
Python 3.10 to 3.13. On macOS and Windows, the official installer from python.org includes Tkinter, which Lens's window needs. On Linux, also install your distribution's Tk package for Python, for example python3-tk on Debian or Ubuntu.
Git, to get Lens and to update it.
uv (optional but recommended), a fast Python package installer that uses the repository's lock file.
Hardware. Lens states no minimum memory or disk requirement. It runs on an ordinary laptop; large report trees take longer to scan, not more memory to install.

An API key is optional. Lens starts and works without one, and deterministic analysis is always available; only the generative explanations need a key.

Install

None of these steps need administrator rights; everything lands in a folder you own. If installing Python itself asks for an administrator password, that is the Python installer, not Lens.

Clone the repository and go into it. The folder you land in is the project root for every command below.
```
git clone https://github.com/MachAI-Inc/chipcopilot.git
cd chipcopilot
```
Create a virtual environment named .venv inside it and activate it. The launcher looks for exactly this folder, so you never need to tell Lens which Python to use.
```
python3 -m venv .venv
source .venv/bin/activate          # macOS and Linux
.venv\Scripts\activate.bat         # Windows (cmd)
.venv\Scripts\Activate.ps1         # Windows (PowerShell)
```
Check with python --version that it reports 3.10 to 3.13.
Install the dependencies into that environment. With uv:
```
pip install uv
uv sync
python -m pip install -r requirements.txt
```
Without uv:
```
python -m pip install "anthropic>=0.39.0" "matplotlib>=3.5.0" pillow "customtkinter>=5.2.2"
```
Use python -m pip, not a bare pip, so the packages go into the environment that will run Lens. Do not install from chipcopilot_flow/src/chipcopilot_flow/gui/requirements.txt; the root requirements.txt is the right file.

Update to a new release

From the project root, with the environment active:

git pull
uv sync
python -m pip install -r requirements.txt

Your projects and settings live outside the repository (see Where your settings live), so updating never touches them.

First launch

There is no application icon yet; Lens starts from a command. From the project root, with the environment active:

python chipcopilot_flow/src/chipcopilot_flow/gui/run_gui.py

On macOS and Linux you can instead run ./restart_gui.sh (after chmod +x restart_gui.sh once), which finds the .venv for you.

At launch Lens checks its own dependencies against the Python that is running it. If anything is missing or the wrong version, a dialog names the cause, the interpreter and the exact command that fixes it. The check never blocks startup: deterministic analysis keeps working, and only the generative actions are affected until you fix it.

If Lens does not start

A three-line message in the terminal naming an interpreter and a missing package means the launcher found a Python that cannot run Lens. Activate .venv and repeat step 3 of the install using python -m pip.
No module named tkinter on Linux means the Tk package is missing: install python3-tk (or your distribution's equivalent) and start again.
python --version outside 3.10 to 3.13: create the .venv again with a supported Python.
Anything else: send the terminal output to the Lens team.

The first time you start Lens, the Welcome tab walks you through setting up a project. It is a guided setup in three steps, and it keeps the steps in order so that you never reach Timing Review with a project that is not set up.

Step 1 — Project. Create or open a project, and give it a name.
Step 2 — Analysis Setup. Under Add your data sources, tick one card for each tool whose reports the project should read: Fusion Compiler and Innovus under Implementation (Synthesis & Place-and-Route), PrimeTime and Tempus under Signoff Timing (STA). Fusion Compiler is ticked by default. Each ticked card asks for the directories where that tool's reports are.
Step 3 — What Happens Next. Before the project is created, this step shows a roadmap of what comes next.

You need to complete only Steps 1 and 2, and then click Create Project. The button stays disabled until every directory a ticked card requires is filled in and valid; once the project exists it reads ✓ Project Created.

When the project is created, Steps 1 and 2 lock to it, and Step 3 becomes a checklist of next steps: configure the tool context, scan scenarios, run the analysis, and open Timing Review. Lens highlights the first step you have not done and keeps later steps disabled until the earlier ones are done. Open Timing Review is always the last step, and it never runs automatically.

Once your project is set up, the Welcome tab leaves the sidebar. To create another project, use Settings > New Project, which shows the Welcome tab again.

Add the optional API key

Digital Soul is the copilot built into Lens. Its generative explanations need an API key from Anthropic, the one provider Lens works with. Without a key, everything still works deterministically, and explanation cards carry a Deterministic fallback badge.

Open Settings > LLM Configuration.
Turn on Enable LLM-powered explanations.
Paste your key into API Key.
Click Test Connection to verify the key.

There is no Save button: the key is saved the moment the API Key field loses focus (click or tab elsewhere), and the other settings on this screen save as you change them. If the field is blank, Lens uses the ANTHROPIC_API_KEY environment variable when your terminal has one; a key typed into Settings takes precedence over it. With neither, Digital Soul runs in deterministic-only mode.

If you turn on explanations and add a key, generative actions send a structured evidence pack, never raw report, log or SDC text. For more, see Data and privacy.

Where your settings live

Lens keeps its settings and your project data under ~/.chipcopilot/:

~/.chipcopilot/
├── machine_settings.json              settings for this machine, and your overrides
└── users/{username}/
    ├── user_config.json               last viewed project, default UI preferences
    └── projects/
        ├── project_registry.json      project list, current project
        └── {project_name}/
            ├── settings.json          directories, current build, extraction pattern
            └── timing_review_data/
                ├── ui_prefs.json      the project's UI state in Timing Review and Lens Compare
                ├── build_registry.json    registered builds, active build for each tool
                └── builds/{build_name}/
                    ├── run_metadata.json              index of the runs for this build
                    └── timing_review_{run_id}.json    one file per run

The folder is .chipcopilot in your home directory, so {username} is your login name on the machine, and ~/.chipcopilot/ means the same place. To keep Lens's data somewhere else, set the CHIPCOPILOT_DATA_DIR environment variable to that folder before starting Lens.

The cache for net-segment analysis lives under cache/longnet/ inside that same data folder.

Saved runs are kept per project and per build, under builds/{build_name}/.
UI preferences are kept per project: one ui_prefs.json is shared by all the builds in the project.
A saved run stores summary results, not individual paths. Lens rebuilds path evidence from your configured reports when it is needed.
Lens writes nothing to your report tree. It only reads your design data.
Lens stores the API key, and every other setting you change, in ~/.chipcopilot/machine_settings.json, a plain JSON file on your machine that Lens never copies anywhere. Protect that file as you would any file holding a secret.

Still have a question?

Updated 19 October 2026