Profpatsch/users/Profpatsch/agent-last-position

View full contents ↓

Track and jump to AI agent's last edited file position.

A Varlink service for editor integration.

nix profile install https://sources.profpatsch.de/Profpatsch.tar.gz#agent-last-position

See the manual page for full documentation:

man ./agent-last-position.1

Or after installation:

man agent-last-position


# Start the service
systemctl --user start agent-last-position.service

# Test it works correctly
agent-last-position set /tmp/test.txt 42
agent-last-position open

agent-last-position(1)

agent-last-position - track and jump to AI agent's last edited file position

agent-last-position server
agent-last-position set path line
agent-last-position get
agent-last-position open
agent-last-position info
agent-last-position hook
agent-last-position prev path line
agent-last-position next path line

agent-last-position is a Varlink-based IPC service that tracks a history of file positions edited by AI agents (OpenCode, Claude, etc.). It enables quick navigation backward and forward through edit locations via editor integration and shell keybindings.

The service maintains an in-memory history of positions (file path and line number) and communicates over a Unix socket at /run/user/<uid>/de.Profpatsch.AgentLastPosition. When an AI agent edits multiple blocks in a single file, each block is recorded as a separate history entry for fine-grained navigation.

The following subcommands are available:

server

Start the Varlink service daemon. The service listens on a Unix socket and maintains the last edited position in memory. This should typically be run as a systemd user service.

set path line

Update the tracked position to the specified file path and line number. This is typically called automatically by AI agent hooks after file edits.

get

Retrieve the current tracked position as JSON output with path and line fields.

open

Open the last edited position in the editor specified by EDITOR. Automatically detects and uses the correct line-jump syntax for vim, emacs, and VSCode. Falls back to generic +line syntax for other editors.

info

Display service information including version and available Varlink interfaces.

hook

Parse Claude Code hook JSON payload from stdin and add positions to history. For Edit tools, extracts line numbers from each hunk in the structured patch, creating multiple history entries for edits in different file locations. Designed to be used directly as a Claude Code hook command.

prev path line

Navigate to the previous position in edit history relative to the given location. Outputs the previous position in path:line format. Returns exit code 1 if at the beginning of history.

next path line

Navigate to the next position in edit history relative to the given location. Outputs the next position in path:line format. Returns exit code 1 if at the end of history.

Build and install using Nix flakes:

$ nix profile install git+https://codeberg.org/Profpatsch/Profpatsch?ref=canon#claude-last-position

This installs claude-last-position and the man page to your Nix profile.

Copy the service file and enable it for automatic startup:

$ cp ~/kot/Profpatsch/users/Profpatsch/claude-last-position/\
    claude-last-position.service ~/.config/systemd/user/
$ systemctl --user daemon-reload
$ systemctl --user enable claude-last-position.service
$ systemctl --user start claude-last-position.service

Add hooks to ~/.claude/settings.json to automatically track edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "claude-last-position hook"
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "claude-last-position hook"
          }
        ]
      }
    ]
  }
}

The hook command reads JSON event data from stdin and extracts accurate line numbers from the structured patch information.

Bash/Zsh (~/.bashrc or ~/.zshrc):

bind -x '"\C-xp": claude-last-position open'

Fish (~/.config/fish/config.fish):

function binding_claude_last_position_open
    commandline -r "claude-last-position open"
    commandline -f execute
end
bind \co binding_claude_last_position_open

The fish binding uses commandline -f execute to ensure the editor receives proper terminal control.

The service implements the following Varlink interface:

interface de.profpatsch.ClaudeLastPosition

type Action (
  method: string,
  description: string,
  prefilled_parameters: object
)

method SetLastPosition(path: string, line: int) -> ()
method GetLastPosition() -> (path: string, line: int, available_actions: []Action)

The interface follows HATEOAS principles: GetLastPosition returns available_actions that describe what operations are available from the current state. External clients discover navigation operations (previous/next) through these actions rather than hardcoded API knowledge. The prev and next CLI commands use internal implementation methods for efficient editor integration.

$ claude-last-position server


$ claude-last-position set /path/to/file.go 42


$ claude-last-position get

{"path": /path/to/file.go, line: 42}


$ claude-last-position open

This opens EDITOR at the tracked file and line.

$ claude-last-position prev /path/to/file.go 42

/path/to/other.go:15

$ claude-last-position next /path/to/other.go 15

/path/to/file.go:42

These commands enable backward and forward navigation through the edit history, useful for editor plugin integration.

EDITOR

Editor command to use for the open subcommand. Defaults to vim if not set. Supported editors include vim, neovim, emacs, and VSCode.

/run/user/<uid>/de.Profpatsch.ClaudeLastPosition

Unix domain socket where the Varlink service listens for client connections.

~/.config/systemd/user/claude-last-position.service

Systemd user service file for automatic startup.

.claude/settings.json

Claude Code settings file where hooks are configured.

The agent-last-position utility exits 0 on success, and >0 if an error occurs.

systemctl(1), varlink(7)

Varlink Protocol: https://varlink.org

Profpatsch

agent-last-position was created with
Claude Code.