diff --git a/pkg/avatar/provider_test.go b/pkg/avatar/provider_test.go
new file mode 100644
index 0000000..987edc4
--- /dev/null
+++ b/pkg/avatar/provider_test.go
@@ -0,0 +1,139 @@
+package avatar
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestURL_DiceBear(t *testing.T) {
+	opts := DefaultOptions()
+	u := URL(ProviderDiceBear, "test-bot", opts)
+
+	if !strings.HasPrefix(u, "https://api.dicebear.com/9.x/bottts/png") {
+		t.Errorf("unexpected DiceBear URL prefix: %s", u)
+	}
+	if !strings.Contains(u, "seed=test-bot") {
+		t.Errorf("URL should contain seed=test-bot: %s", u)
+	}
+	if !strings.Contains(u, "size=256") {
+		t.Errorf("URL should contain size=256: %s", u)
+	}
+}
+
+func TestURL_DiceBear_CustomStyle(t *testing.T) {
+	opts := DefaultOptions()
+	opts.DiceBearStyle = DiceBearPixelArt
+	u := URL(ProviderDiceBear, "my-agent", opts)
+
+	if !strings.Contains(u, "/pixel-art/png") {
+		t.Errorf("URL should use pixel-art style: %s", u)
+	}
+}
+
+func TestURL_RoboHash(t *testing.T) {
+	opts := DefaultOptions()
+	u := URL(ProviderRoboHash, "robot-1", opts)
+
+	if !strings.HasPrefix(u, "https://robohash.org/robot-1.png") {
+		t.Errorf("unexpected RoboHash URL prefix: %s", u)
+	}
+	if !strings.Contains(u, "set=set1") {
+		t.Errorf("URL should contain set=set1: %s", u)
+	}
+	if !strings.Contains(u, "size=256x256") {
+		t.Errorf("URL should contain size=256x256: %s", u)
+	}
+}
+
+func TestURL_RoboHash_CustomSet(t *testing.T) {
+	opts := DefaultOptions()
+	opts.RoboHashSet = RoboHashCats
+	u := URL(ProviderRoboHash, "cat-bot", opts)
+
+	if !strings.Contains(u, "set=set4") {
+		t.Errorf("URL should contain set=set4 for cats: %s", u)
+	}
+}
+
+func TestURL_Multiavatar(t *testing.T) {
+	u := URL(ProviderMultiavatar, "multi-bot", DefaultOptions())
+
+	if !strings.HasPrefix(u, "https://api.multiavatar.com/multi-bot.png") {
+		t.Errorf("unexpected Multiavatar URL: %s", u)
+	}
+}
+
+func TestURL_CustomSize(t *testing.T) {
+	opts := DefaultOptions()
+	opts.Size = 512
+	u := URL(ProviderDiceBear, "big-bot", opts)
+
+	if !strings.Contains(u, "size=512") {
+		t.Errorf("URL should contain size=512: %s", u)
+	}
+}
+
+func TestURL_ZeroSize_DefaultsTo256(t *testing.T) {
+	opts := Options{Size: 0}
+	u := URL(ProviderDiceBear, "zero", opts)
+
+	if !strings.Contains(u, "size=256") {
+		t.Errorf("zero size should default to 256: %s", u)
+	}
+}
+
+func TestURL_UnknownProvider_FallsToDiceBear(t *testing.T) {
+	u := URL(Provider("unknown"), "fallback", DefaultOptions())
+
+	if !strings.HasPrefix(u, "https://api.dicebear.com/") {
+		t.Errorf("unknown provider should fall back to DiceBear: %s", u)
+	}
+}
+
+func TestURL_SpecialCharsInSeed(t *testing.T) {
+	u := URL(ProviderDiceBear, "bot with spaces", DefaultOptions())
+
+	if strings.Contains(u, " ") {
+		t.Errorf("URL should not contain raw spaces: %s", u)
+	}
+}
+
+func TestAllProviders(t *testing.T) {
+	providers := AllProviders()
+	if len(providers) != 3 {
+		t.Errorf("expected 3 providers, got %d", len(providers))
+	}
+}
+
+func TestDefaultOptions(t *testing.T) {
+	opts := DefaultOptions()
+	if opts.Size != 256 {
+		t.Errorf("expected default size 256, got %d", opts.Size)
+	}
+	if opts.DiceBearStyle != DiceBearBottts {
+		t.Errorf("expected default style bottts, got %s", opts.DiceBearStyle)
+	}
+	if opts.RoboHashSet != RoboHashRobots {
+		t.Errorf("expected default set set1, got %s", opts.RoboHashSet)
+	}
+}
+
+func TestURL_Deterministic(t *testing.T) {
+	opts := DefaultOptions()
+	u1 := URL(ProviderDiceBear, "same-seed", opts)
+	u2 := URL(ProviderDiceBear, "same-seed", opts)
+
+	if u1 != u2 {
+		t.Errorf("same seed should produce same URL:\n  %s\n  %s", u1, u2)
+	}
+}
+
+func TestURL_DifferentSeeds_DifferentURLs(t *testing.T) {
+	opts := DefaultOptions()
+	u1 := URL(ProviderDiceBear, "bot-a", opts)
+	u2 := URL(ProviderDiceBear, "bot-b", opts)
+
+	if u1 == u2 {
+		t.Error("different seeds should produce different URLs")
+	}
+}
diff --git a/shell/avatar/fetch_test.go b/shell/avatar/fetch_test.go
new file mode 100644
index 0000000..190940f
--- /dev/null
+++ b/shell/avatar/fetch_test.go
@@ -0,0 +1,137 @@
+package avatar
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestDownload_OK(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.Write([]byte("fake-png-data"))
+	}))
+	defer srv.Close()
+
+	path, err := Download(context.Background(), srv.URL+"/avatar.png")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	defer os.Remove(path)
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read temp file: %v", err)
+	}
+	if string(data) != "fake-png-data" {
+		t.Errorf("unexpected content: %q", data)
+	}
+
+	if ext := filepath.Ext(path); ext != ".png" {
+		t.Errorf("expected .png extension, got %q", ext)
+	}
+}
+
+func TestDownload_JPEG(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/jpeg")
+		w.Write([]byte("fake-jpeg"))
+	}))
+	defer srv.Close()
+
+	path, err := Download(context.Background(), srv.URL+"/photo.jpg")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	defer os.Remove(path)
+
+	if ext := filepath.Ext(path); ext != ".jpg" {
+		t.Errorf("expected .jpg extension, got %q", ext)
+	}
+}
+
+func TestDownload_HTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	_, err := Download(context.Background(), srv.URL+"/missing.png")
+	if err == nil {
+		t.Fatal("expected error for 404")
+	}
+}
+
+func TestDownload_ContextCancelled(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("data"))
+	}))
+	defer srv.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := Download(ctx, srv.URL+"/test.png")
+	if err == nil {
+		t.Fatal("expected error for cancelled context")
+	}
+}
+
+func TestFetchToDir(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.Write([]byte("avatar-image"))
+	}))
+	defer srv.Close()
+
+	dir := t.TempDir()
+
+	// We need to mock the provider URL. Instead, test Download + manual copy logic.
+	// FetchToDir uses Fetch internally which hits real providers.
+	// Test the Download path which is the impure core.
+	path, err := Download(context.Background(), srv.URL+"/bot.png")
+	if err != nil {
+		t.Fatalf("download: %v", err)
+	}
+	defer os.Remove(path)
+
+	// Verify the file exists in temp
+	if _, err := os.Stat(path); err != nil {
+		t.Fatalf("temp file missing: %v", err)
+	}
+
+	// Verify content
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	if string(data) != "avatar-image" {
+		t.Errorf("unexpected content: %q", data)
+	}
+	_ = dir // used via t.TempDir for cleanup
+}
+
+func TestExtensionFromContentType(t *testing.T) {
+	tests := []struct {
+		ct   string
+		want string
+	}{
+		{"image/png", ".png"},
+		{"image/jpeg", ".jpg"},
+		{"image/svg+xml", ".svg"},
+		{"image/webp", ".webp"},
+		{"image/gif", ".gif"},
+		{"application/octet-stream", ".png"},
+		{"", ".png"},
+	}
+
+	for _, tt := range tests {
+		got := extensionFromContentType(tt.ct)
+		if got != tt.want {
+			t.Errorf("extensionFromContentType(%q) = %q, want %q", tt.ct, got, tt.want)
+		}
+	}
+}