First workspace

This walkthrough gets a new project from launch to an AI-assisted edit in a few minutes.

1. Open a workspace

Start Voktty and choose a local directory from the workspace selector. The first workspace is the root that the explorer, Git integration and AI tools use for authorization and path resolution.

The shell starts in the selected directory. The active path is shown in the status bar and updates as the shell emits OSC 7 directory markers.

2. Run a command

Open a terminal tab with Ctrl+T on Windows and Linux or Cmd+T on macOS. Type a normal shell command and press Enter. Voktty sends carriage return input to the PTY so PowerShell and Unix shells receive the same interactive behavior.

Use Ctrl+D or the shell's normal exit command to end a session. Closing a tab also closes its PTY session and its descendants according to the platform process-lifecycle rules.

3. Split the view

Use Ctrl+D to split right and Ctrl+Shift+D to split down. Each pane has its own terminal, editor or preview leaf while remaining part of the same tab layout. Use Ctrl+] and Ctrl+[ to move focus between panes.

4. Open a file

Use the explorer or Ctrl+O to open a file in CodeMirror. The editor keeps buffers in LF form and restores the file's original line ending style when saving. If the file changed on disk after it was opened, Voktty asks whether to overwrite rather than silently losing another writer's changes.

5. Enable AI

Open Settings with Ctrl+,, choose AI, select a provider and add a key. Keys are stored through the operating system keychain. Local providers such as Ollama, LM Studio and MLX can be configured without a cloud key.

Open the AI panel with Ctrl+I. Ask a read-only question first, such as:

Explain the structure of this workspace and point out the main entry point.

The agent can read authorized files and search the workspace automatically. Actions that mutate files, run commands or start background processes are shown for approval.

6. Review an edit

Ask the agent for a focused change:

Add a test for the error path in the parser, then show me the proposed edit.

Voktty opens AI edits in a diff tab. Review each hunk and accept or reject it. The underlying write happens only after the diff is accepted.

7. Check your changes

Open the source-control panel with Ctrl+G. Inspect the diff, stage selected changes, write a commit message and commit with Ctrl+Enter or Cmd+Enter on macOS. Push and pull actions remain explicit and are gated by the workspace authorization model.

A useful first-session checklist

  • [ ] Choose the project root.
  • [ ] Confirm the shell and current directory.
  • [ ] Open one source file and one terminal pane.
  • [ ] Configure a cloud or local AI provider.
  • [ ] Try a read-only AI request before approving a mutation.
  • [ ] Review the Git diff before committing.