getting-started.md

Your first coding task

In this tutorial, you will ask DeepCode to write a small Python function, review the changes, run its tests, and return to the conversation later. You can follow along in the terminal, Desktop, or your browser.

You will need DeepCode, access to a model provider, and Python to run the example. The task uses Python's standard library, so there are no extra test dependencies to install.

1 · Install DeepCode

With uv installed, open a terminal and run:

uv tool install --python 3.12 deepcode-hku
deepcode init

If you already installed DeepCode, skip this step. For installation from source or help setting up uv, see installation. If your terminal cannot find deepcode, run uv tool update-shell and open a new terminal.

Choose how you would like to work:

Interface	Open it with	Setup
Terminal UI	deepcode	Included with the CLI installation
Desktop	deepcode desktop	Also install the Desktop app
Browser	deepcode web	Open the link generated by the command

The steps below use the terminal. Desktop and Web instructions appear alongside them, so you can follow the same exercise in either interface.

2 · Connect a model

For this example, you will use OpenRouter. Have your provider's API key ready, then run:

deepcode provider set my-openrouter --template openrouter --api-key
deepcode provider models my-openrouter --refresh

Enter your key at the prompt; it stays hidden as you type. The second command lists the available models. Choose one and replace MODEL_ID in the commands below with its full ID:

deepcode provider test my-openrouter --model MODEL_ID

This sends a short request to check that you can use the model. If it fails, check the key and model ID before continuing.

Using Desktop or Web? Open Settings → AI providers, click Add provider, and enter your key. Click Save and check to load the models, then choose one under Agent model and click Save and verify model. Select that connection and model in your conversation's message box when you open the project below.

For a different provider or a local model, follow Models and providers.

3 · Open a project folder

Create a folder for the exercise and start DeepCode there:

mkdir deepcode-demo
cd deepcode-demo
deepcode --trust --connection my-openrouter --model MODEL_ID

Choose a different folder name if deepcode-demo already exists. --trust tells DeepCode that you trust this folder and want to work in it. You only need to record that trust once for each project. DeepCode will still ask about tool actions that require your approval.

Using Desktop or Web? Create the folder, add it as a Project, confirm that you trust it, and click New thread. A thread is a saved conversation about your project. You will also see it called a Session in the TUI.

Before sending the task, check the selected model. In the TUI, /model opens the model picker; Desktop and Web show the selection beside the message box.

4 · Ask DeepCode to write the function

Paste this message into the conversation:

Create greeting.py with a greet(name) function. Strip surrounding whitespace
and return "Hello, <name>!". Raise ValueError if the stripped name is empty.
Create test_greeting.py using Python's standard-library unittest to cover a
normal name, surrounding whitespace, and an empty name. Use no external
dependencies. Run python -m unittest discover -v and summarize the changes
and test results.

If you normally run Python as python3 or py -3, use that command in the message instead of python.

As DeepCode works, the conversation shows which files it reads or changes and which commands it runs. If an approval appears, review the proposed action and choose whether to allow it. In the TUI:

Response	What it allows
y	This action once
a	This tool for the rest of the current Session
n	Deny this action

Desktop and Web show buttons for answering the same requests. You can send a follow-up message while DeepCode works to clarify a requirement. To interrupt the current task, press Esc in the TUI or use the stop button in Desktop/Web.

5 · Review the code and run the tests

Open greeting.py and test_greeting.py in your editor or the Desktop/Web file panel. Look for the behavior you requested: trimming spaces, formatting the greeting, and rejecting an empty name.

Open another terminal in deepcode-demo and run the tests yourself:

python -m unittest discover -v

Use python3 or py -3 here too if you used it above. The test runner should report that the tests passed, ending with OK. If a test fails, paste the failure into the conversation and ask DeepCode to fix it.

You can keep building on the same task. For example:

Add a test for a name containing only spaces. Run the tests again and fix
anything needed so that this also raises ValueError.

When working in an existing repository, use this same workflow: describe the change, review the diff, and run the relevant tests.

6 · Come back to the conversation

In the TUI, give the conversation a name:

/rename Greeting exercise

Use /exit or Ctrl+D when you are done. Next time, run deepcode from the same folder and enter /resume. Choose Greeting exercise to continue. If you saved its Session ID, you can also open it directly:

deepcode --resume SESSION_ID

Replace SESSION_ID with your conversation's ID. In Desktop/Web, open the project and select the conversation from its thread list. Try switching to another interface—you can continue the same conversation there.

Closing the interface leaves a running task in the background. To stop work, use /stop or the stop button before closing it. If you lose your connection, follow Troubleshooting to return to the task.

Try next

• Use the terminal UI: attach files, choose Skills, and queue tasks.
• Manage conversations: resume work and make room in long chats.
• Add project instructions: teach DeepCode your conventions.
• Work on larger goals: continue a task across turns or run it on a schedule.